perf: 50% faster compilation speed by skipping bundling of server-only packages during dev (#11594)

AlessioGr · web-flow · commit c7bb69424992 · 2025-03-11T09:45:13.000-06:00
This PR skips bundling server-only payload packages during development, which results in 50% faster compilation speeds using turbo.

Test results using our blank template (both /api and /admin):

Webpack before: 11.5
Webpack now: 7.1s
=&gt; 38% faster compilation speed

Turbopack before: 4.1s
Turbopack after: 2.1s
=&gt; 50% faster compilation speed
diff --git a/next.config.mjs b/next.config.mjs
@@ -12,54 +12,57 @@ const withBundleAnalyzer = bundleAnalyzer({
 })
 
 const config = withBundleAnalyzer(
-  withPayload({
-    eslint: {
-      ignoreDuringBuilds: true,
-    },
-    typescript: {
-      ignoreBuildErrors: true,
-    },
-    experimental: {
-      fullySpecified: true,
-      serverActions: {
-        bodySizeLimit: '5mb',
+  withPayload(
+    {
+      eslint: {
+        ignoreDuringBuilds: true,
       },
-    },
-    env: {
-      PAYLOAD_CORE_DEV: 'true',
-      ROOT_DIR: path.resolve(dirname),
-      // @todo remove in 4.0 - will behave like this by default in 4.0
-      PAYLOAD_DO_NOT_SANITIZE_LOCALIZED_PROPERTY: 'true',
-    },
-    async redirects() {
-      return [
-        {
-          destination: '/admin',
-          permanent: false,
-          source: '/',
+      typescript: {
+        ignoreBuildErrors: true,
+      },
+      experimental: {
+        fullySpecified: true,
+        serverActions: {
+          bodySizeLimit: '5mb',
         },
-      ]
-    },
-    images: {
-      domains: ['localhost'],
-    },
-    webpack: (webpackConfig) => {
-      webpackConfig.resolve.extensionAlias = {
-        '.cjs': ['.cts', '.cjs'],
-        '.js': ['.ts', '.tsx', '.js', '.jsx'],
-        '.mjs': ['.mts', '.mjs'],
-      }
+      },
+      env: {
+        PAYLOAD_CORE_DEV: 'true',
+        ROOT_DIR: path.resolve(dirname),
+        // @todo remove in 4.0 - will behave like this by default in 4.0
+        PAYLOAD_DO_NOT_SANITIZE_LOCALIZED_PROPERTY: 'true',
+      },
+      async redirects() {
+        return [
+          {
+            destination: '/admin',
+            permanent: false,
+            source: '/',
+          },
+        ]
+      },
+      images: {
+        domains: ['localhost'],
+      },
+      webpack: (webpackConfig) => {
+        webpackConfig.resolve.extensionAlias = {
+          '.cjs': ['.cts', '.cjs'],
+          '.js': ['.ts', '.tsx', '.js', '.jsx'],
+          '.mjs': ['.mts', '.mjs'],
+        }
 
-      // Ignore sentry warnings when not wrapped with withSentryConfig
-      webpackConfig.ignoreWarnings = [
-        ...(webpackConfig.ignoreWarnings ?? []),
-        { file: /esm\/platform\/node\/instrumentation.js/ },
-        { module: /esm\/platform\/node\/instrumentation.js/ },
-      ]
+        // Ignore sentry warnings when not wrapped with withSentryConfig
+        webpackConfig.ignoreWarnings = [
+          ...(webpackConfig.ignoreWarnings ?? []),
+          { file: /esm\/platform\/node\/instrumentation.js/ },
+          { module: /esm\/platform\/node\/instrumentation.js/ },
+        ]
 
-      return webpackConfig
+        return webpackConfig
+      },
     },
-  }),
+    { devBundleServerPackages: false },
+  ),
 )
 
 export default process.env.NEXT_PUBLIC_SENTRY_DSN
diff --git a/packages/next/src/withPayload.js b/packages/next/src/withPayload.js
@@ -1,9 +1,11 @@
 /**
  * @param {import('next').NextConfig} nextConfig
+ * @param {Object} [options] - Optional configuration options
+ * @param {boolean} [options.devBundleServerPackages] - Whether to bundle server packages in development mode. @default true
  *
  * @returns {import('next').NextConfig}
  * */
-export const withPayload = (nextConfig = {}) => {
+export const withPayload = (nextConfig = {}, options = {}) => {
   const env = nextConfig?.env || {}
 
   if (nextConfig.experimental?.staleTimes?.dynamic) {
@@ -99,6 +101,32 @@ export const withPayload = (nextConfig = {}) => {
       'libsql',
       'pino-pretty',
       'graphql',
+      // Do not bundle server-only packages during dev to improve compile speed
+      ...(process.env.npm_lifecycle_event === 'dev' && options.devBundleServerPackages === false
+        ? [
+            'payload',
+            '@payloadcms/db-mongodb',
+            '@payloadcms/db-postgres',
+            '@payloadcms/db-sqlite',
+            '@payloadcms/db-vercel-postgres',
+            '@payloadcms/drizzle',
+            '@payloadcms/email-nodemailer',
+            '@payloadcms/email-resend',
+            '@payloadcms/graphql',
+            '@payloadcms/payload-cloud',
+            '@payloadcms/plugin-cloud-storage',
+            '@payloadcms/plugin-redirects',
+            '@payloadcms/plugin-sentry',
+            '@payloadcms/plugin-stripe',
+            // TODO: Add the following packages, excluding their /client subpath exports, once Next.js supports it
+            // @payloadcms/richtext-lexical
+            //'@payloadcms/storage-azure',
+            //'@payloadcms/storage-gcs',
+            //'@payloadcms/storage-s3',
+            //'@payloadcms/storage-uploadthing',
+            //'@payloadcms/storage-vercel-blob',
+          ]
+        : []),
     ],
     webpack: (webpackConfig, webpackOptions) => {
       const incomingWebpackConfig =
diff --git a/packages/payload-cloud/src/utilities/refreshSession.ts b/packages/payload-cloud/src/utilities/refreshSession.ts
@@ -1,12 +1,12 @@
 import { CognitoIdentityClient } from '@aws-sdk/client-cognito-identity'
-import * as AWS from '@aws-sdk/client-s3'
+import { S3 } from '@aws-sdk/client-s3'
 import { fromCognitoIdentityPool } from '@aws-sdk/credential-providers'
 
 import { authAsCognitoUser } from './authAsCognitoUser.js'
 
 export type GetStorageClient = () => Promise<{
   identityID: string
-  storageClient: AWS.S3
+  storageClient: S3
 }>
 
 export const refreshSession = async () => {
@@ -33,7 +33,7 @@ export const refreshSession = async () => {
   // @ts-expect-error - Incorrect AWS types
   const identityID = credentials.identityId
 
-  const storageClient = new AWS.S3({
+  const storageClient = new S3({
     credentials,
     region: process.env.PAYLOAD_CLOUD_BUCKET_REGION,
   })
diff --git a/templates/_template/next.config.mjs b/templates/_template/next.config.mjs
@@ -5,4 +5,4 @@ const nextConfig = {
   // Your Next.js config here
 }
 
-export default withPayload(nextConfig)
+export default withPayload(nextConfig, { devBundleServerPackages: false })
diff --git a/templates/blank/next.config.mjs b/templates/blank/next.config.mjs
@@ -5,4 +5,4 @@ const nextConfig = {
   // Your Next.js config here
 }
 
-export default withPayload(nextConfig)
+export default withPayload(nextConfig, { devBundleServerPackages: false })
diff --git a/templates/plugin/dev/next.config.mjs b/templates/plugin/dev/next.config.mjs
@@ -18,4 +18,4 @@ const nextConfig = {
   // transpilePackages: ['../src'],
 }
 
-export default withPayload(nextConfig)
+export default withPayload(nextConfig, { devBundleServerPackages: false })
diff --git a/templates/website/next.config.js b/templates/website/next.config.js
@@ -24,4 +24,4 @@ const nextConfig = {
   redirects,
 }
 
-export default withPayload(nextConfig)
+export default withPayload(nextConfig, { devBundleServerPackages: false })
diff --git a/templates/with-payload-cloud/next.config.mjs b/templates/with-payload-cloud/next.config.mjs
@@ -5,4 +5,4 @@ const nextConfig = {
   // Your Next.js config here
 }
 
-export default withPayload(nextConfig)
+export default withPayload(nextConfig, { devBundleServerPackages: false })
diff --git a/templates/with-postgres/next.config.mjs b/templates/with-postgres/next.config.mjs
@@ -5,4 +5,4 @@ const nextConfig = {
   // Your Next.js config here
 }
 
-export default withPayload(nextConfig)
+export default withPayload(nextConfig, { devBundleServerPackages: false })
diff --git a/templates/with-vercel-mongodb/next.config.mjs b/templates/with-vercel-mongodb/next.config.mjs
@@ -5,4 +5,4 @@ const nextConfig = {
   // Your Next.js config here
 }
 
-export default withPayload(nextConfig)
+export default withPayload(nextConfig, { devBundleServerPackages: false })
diff --git a/templates/with-vercel-postgres/next.config.mjs b/templates/with-vercel-postgres/next.config.mjs
@@ -5,4 +5,4 @@ const nextConfig = {
   // Your Next.js config here
 }
 
-export default withPayload(nextConfig)
+export default withPayload(nextConfig, { devBundleServerPackages: false })
diff --git a/templates/with-vercel-website/next.config.js b/templates/with-vercel-website/next.config.js
@@ -24,4 +24,4 @@ const nextConfig = {
   redirects,
 }
 
-export default withPayload(nextConfig)
+export default withPayload(nextConfig, { devBundleServerPackages: false })
diff --git a/test/next.config.mjs b/test/next.config.mjs
@@ -12,45 +12,48 @@ const withBundleAnalyzer = bundleAnalyzer({
 })
 
 export default withBundleAnalyzer(
-  withPayload({
-    eslint: {
-      ignoreDuringBuilds: true,
-    },
-    typescript: {
-      ignoreBuildErrors: true,
-    },
-    experimental: {
-      fullySpecified: true,
-      serverActions: {
-        bodySizeLimit: '5mb',
+  withPayload(
+    {
+      eslint: {
+        ignoreDuringBuilds: true,
       },
-    },
-    env: {
-      PAYLOAD_CORE_DEV: 'true',
-      ROOT_DIR: path.resolve(dirname),
-      // @todo remove in 4.0 - will behave like this by default in 4.0
-      PAYLOAD_DO_NOT_SANITIZE_LOCALIZED_PROPERTY: 'true',
-    },
-    async redirects() {
-      return [
-        {
-          destination: '/admin',
-          permanent: true,
-          source: '/',
+      typescript: {
+        ignoreBuildErrors: true,
+      },
+      experimental: {
+        fullySpecified: true,
+        serverActions: {
+          bodySizeLimit: '5mb',
         },
-      ]
-    },
-    images: {
-      domains: ['localhost'],
-    },
-    webpack: (webpackConfig) => {
-      webpackConfig.resolve.extensionAlias = {
-        '.cjs': ['.cts', '.cjs'],
-        '.js': ['.ts', '.tsx', '.js', '.jsx'],
-        '.mjs': ['.mts', '.mjs'],
-      }
+      },
+      env: {
+        PAYLOAD_CORE_DEV: 'true',
+        ROOT_DIR: path.resolve(dirname),
+        // @todo remove in 4.0 - will behave like this by default in 4.0
+        PAYLOAD_DO_NOT_SANITIZE_LOCALIZED_PROPERTY: 'true',
+      },
+      async redirects() {
+        return [
+          {
+            destination: '/admin',
+            permanent: true,
+            source: '/',
+          },
+        ]
+      },
+      images: {
+        domains: ['localhost'],
+      },
+      webpack: (webpackConfig) => {
+        webpackConfig.resolve.extensionAlias = {
+          '.cjs': ['.cts', '.cjs'],
+          '.js': ['.ts', '.tsx', '.js', '.jsx'],
+          '.mjs': ['.mts', '.mjs'],
+        }
 
-      return webpackConfig
+        return webpackConfig
+      },
     },
-  }),
+    { devBundleServerPackages: false },
+  ),
 )

Original file line number	Diff line number	Diff line change
`@@ -5,4 +5,4 @@ const nextConfig = {`
`5`	`5`	`// Your Next.js config here`
`6`	`6`	`}`
`7`	`7`
`8`		`-export default withPayload(nextConfig)`
	`8`	`+export default withPayload(nextConfig, { devBundleServerPackages: false })`
Original file line number	Diff line number	Diff line change
`@@ -18,4 +18,4 @@ const nextConfig = {`
`18`	`18`	`// transpilePackages: ['../src'],`
`19`	`19`	`}`
`20`	`20`
`21`		`-export default withPayload(nextConfig)`
	`21`	`+export default withPayload(nextConfig, { devBundleServerPackages: false })`
Original file line number	Diff line number	Diff line change
`@@ -24,4 +24,4 @@ const nextConfig = {`
`24`	`24`	`redirects,`
`25`	`25`	`}`
`26`	`26`
`27`		`-export default withPayload(nextConfig)`
	`27`	`+export default withPayload(nextConfig, { devBundleServerPackages: false })`