feat: support turbopack build on Next.js canaries

next.config.mjs

@@ -1,6 +1,6 @@
 import bundleAnalyzer from '@next/bundle-analyzer'
 import { withSentryConfig } from '@sentry/nextjs'
-import { withPayload } from './packages/next/src/withPayload.js'
+import { withPayload } from './packages/next/src/withPayload/withPayload.js'
 import path from 'path'
 import { fileURLToPath } from 'url'
 

packages/next/bundleWithPayload.js

@@ -0,0 +1,23 @@
+/**
+ * This file creates a cjs-compatible bundle of the withPayload function.
+ */
+
+import * as esbuild from 'esbuild'
+import path from 'path'
+
+await esbuild.build({
+  entryPoints: ['dist/withPayload/withPayload.js'],
+  bundle: true,
+  platform: 'node',
+  format: 'cjs',
+  outfile: `dist/cjs/withPayload.cjs`,
+  splitting: false,
+  minify: true,
+  metafile: true,
+  tsconfig: path.resolve(import.meta.dirname, 'tsconfig.json'),
+  sourcemap: true,
+  minify: false,
+  // 18.20.2 is the lowest version of node supported by Payload
+  target: 'node18.20.2',
+})
+console.log('withPayload cjs bundle created successfully')

packages/next/eslint.config.js

@@ -21,9 +21,10 @@ export const index = [
           // See comment in packages/eslint-config/index.mjs
           allowDefaultProject: [
             'bundleScss.js',
-            'createStubScss.js',
             'bundle.js',
             'babel.config.cjs',
+            'bundleWithPayload.js',
+            'createStubScss.js',
           ],
         },
       },

packages/next/package.json

@@ -32,8 +32,8 @@
       "default": "./src/index.js"
     },
     "./withPayload": {
-      "import": "./src/withPayload.js",
-      "default": "./src/withPayload.js"
+      "import": "./src/withPayload/withPayload.ts",
+      "default": "./src/withPayload/withPayload.ts"
     },
     "./layouts": {
       "import": "./src/exports/layouts.ts",
@@ -85,7 +85,7 @@
     "build": "pnpm build:reactcompiler",
     "build:babel": "rm -rf dist_optimized && babel dist --out-dir dist_optimized --source-maps --extensions .ts,.js,.tsx,.jsx,.cjs,.mjs && rm -rf dist && mv dist_optimized dist",
     "build:bundle-for-analysis": "rm -rf dist && rm -rf tsconfig.tsbuildinfo && pnpm build:swc && pnpm build:babel && pnpm copyfiles && node ./bundle.js esbuild",
-    "build:cjs": "swc ./src/withPayload.js -o ./dist/cjs/withPayload.cjs --config-file .swcrc-cjs --strip-leading-paths",
+    "build:cjs": "node ./bundleWithPayload.js",
     "build:debug": "rm -rf dist && rm -rf tsconfig.tsbuildinfo && pnpm build:swc:debug && pnpm copyfiles:debug && pnpm build:types && pnpm build:cjs && node createStubScss.js",
     "build:esbuild": "node bundleScss.js",
     "build:reactcompiler": "rm -rf dist && rm -rf tsconfig.tsbuildinfo && pnpm build:swc && pnpm build:babel && pnpm copyfiles && pnpm build:types && pnpm build:esbuild  && pnpm build:cjs",
@@ -156,9 +156,9 @@
         "default": "./dist/prod/styles.css"
       },
       "./withPayload": {
-        "import": "./dist/withPayload.js",
+        "import": "./dist/withPayload/withPayload.js",
         "require": "./dist/cjs/withPayload.cjs",
-        "default": "./dist/withPayload.js"
+        "default": "./dist/withPayload/withPayload.js"
       },
       "./layouts": {
         "import": "./dist/exports/layouts.js",

packages/next/src/index.js

@@ -1 +1 @@
-export { default as withPayload } from './withPayload.js'
+export { default as withPayload } from './withPayload/withPayload.js'

packages/next/src/withPayload.js → packages/next/src/withPayload/withPayload.ts

@@ -1,11 +1,31 @@
+/* eslint-disable no-console */
+/* eslint-disable no-restricted-exports */
+import type { NextConfig } from 'next'
+
+import {
+  getNextjsVersion,
+  supportsTurbopackExternalizeTransitiveDependencies,
+} from './withPayload.utils.js'
+import { withPayloadLegacy } from './withPayloadLegacy.js'
+
+const poweredByHeader = {
+  key: 'X-Powered-By',
+  value: 'Next.js, Payload',
+}
+
 /**
  * @param {import('next').NextConfig} nextConfig
  * @param {Object} [options] - Optional configuration options
  * @param {boolean} [options.devBundleServerPackages] - Whether to bundle server packages in development mode. @default false
- *
- * @returns {import('next').NextConfig}
  * */
-export const withPayload = (nextConfig = {}, options = {}) => {
+export const withPayload = (
+  nextConfig: NextConfig = {},
+  options: { devBundleServerPackages?: boolean } = {},
+): NextConfig => {
+  const nextjsVersion = getNextjsVersion()
+
+  const supportsTurbopackBuild = supportsTurbopackExternalizeTransitiveDependencies(nextjsVersion)
+
   const env = nextConfig.env || {}
 
   if (nextConfig.experimental?.staleTimes?.dynamic) {
@@ -15,67 +35,9 @@ export const withPayload = (nextConfig = {}, options = {}) => {
     env.NEXT_PUBLIC_ENABLE_ROUTER_CACHE_REFRESH = 'true'
   }
 
-  if (process.env.PAYLOAD_PATCH_TURBOPACK_WARNINGS !== 'false') {
-    // TODO: This warning is thrown because we cannot externalize the entry-point package for client-s3, so we patch the warning to not show it.
-    // We can remove this once Next.js implements https://github.com/vercel/next.js/discussions/76991
-    const turbopackWarningText =
-      'Packages that should be external need to be installed in the project directory, so they can be resolved from the output files.\nTry to install it into the project directory by running'
-
-    // TODO 4.0: Remove this once we drop support for Next.js 15.2.x
-    const turbopackConfigWarningText = "Unrecognized key(s) in object: 'turbopack'"
-
-    const consoleWarn = console.warn
-    console.warn = (...args) => {
-      // Force to disable serverExternalPackages warnings: https://github.com/vercel/next.js/issues/68805
-      if (
-        (typeof args[1] === 'string' && args[1].includes(turbopackWarningText)) ||
-        (typeof args[0] === 'string' && args[0].includes(turbopackWarningText))
-      ) {
-        return
-      }
-
-      // Add Payload-specific message after turbopack config warning in Next.js 15.2.x or lower.
-      // TODO 4.0: Remove this once we drop support for Next.js 15.2.x
-      const hasTurbopackConfigWarning =
-        (typeof args[1] === 'string' && args[1].includes(turbopackConfigWarningText)) ||
-        (typeof args[0] === 'string' && args[0].includes(turbopackConfigWarningText))
-
-      if (hasTurbopackConfigWarning) {
-        consoleWarn(...args)
-        consoleWarn(
-          'Payload: You can safely ignore the "Invalid next.config" warning above. This only occurs on Next.js 15.2.x or lower. We recommend upgrading to Next.js 15.4.7 to resolve this warning.',
-        )
-        return
-      }
-
-      consoleWarn(...args)
-    }
-  }
-
-  const isBuild = process.env.NODE_ENV === 'production'
-  const isTurbopackNextjs15 = process.env.TURBOPACK === '1'
-  const isTurbopackNextjs16 = process.env.TURBOPACK === 'auto'
-
-  if (isBuild && (isTurbopackNextjs15 || isTurbopackNextjs16)) {
-    throw new Error(
-      'Payload does not support using Turbopack for production builds. If you are using Next.js 16, please use `next build --webpack` instead.',
-    )
-  }
-
-  const poweredByHeader = {
-    key: 'X-Powered-By',
-    value: 'Next.js, Payload',
-  }
-
-  /**
-   * @type {import('next').NextConfig}
-   */
-  const toReturn = {
+  const baseConfig: NextConfig = {
     ...nextConfig,
     env,
-    turbopack: {
-      ...(nextConfig.turbopack || {}),
-    },
     outputFileTracingExcludes: {
       ...(nextConfig.outputFileTracingExcludes || {}),
       '**/*': [
@@ -88,6 +50,9 @@ export const withPayload = (nextConfig = {}, options = {}) => {
       ...(nextConfig.outputFileTracingIncludes || {}),
       '**/*': [...(nextConfig.outputFileTracingIncludes?.['**/*'] || []), '@libsql/client'],
     },
+    turbopack: {
+      ...(nextConfig.turbopack || {}),
+    },
     // We disable the poweredByHeader here because we add it manually in the headers function below
     ...(nextConfig.poweredByHeader !== false ? { poweredByHeader: false } : {}),
     headers: async () => {
@@ -96,7 +61,6 @@ export const withPayload = (nextConfig = {}, options = {}) => {
       return [
         ...(headersFromConfig || []),
         {
-          source: '/:path*',
           headers: [
             {
               key: 'Accept-CH',
@@ -112,20 +76,14 @@ export const withPayload = (nextConfig = {}, options = {}) => {
             },
             ...(nextConfig.poweredByHeader !== false ? [poweredByHeader] : []),
           ],
+          source: '/:path*',
         },
       ]
     },
     serverExternalPackages: [
-      // serverExternalPackages = webpack.externals, but with turbopack support and an additional check
-      // for whether the package is resolvable from the project root
-      ...(nextConfig.serverExternalPackages || []),
-      // Can be externalized, because we require users to install graphql themselves - we only rely on it as a peer dependency => resolvable from the project root.
-      //
       // WHY: without externalizing graphql, a graphql version error will be thrown
       // during runtime ("Ensure that there is only one instance of \"graphql\" in the node_modules\ndirectory.")
       'graphql',
-      // External, because it installs import-in-the-middle and require-in-the-middle - both in the default serverExternalPackages list.
-      '@sentry/nextjs',
       ...(process.env.NODE_ENV === 'development' && options.devBundleServerPackages !== true
         ? /**
            * Unless explicitly disabled by the user, by passing `devBundleServerPackages: true` to withPayload, we
@@ -208,6 +166,13 @@ export const withPayload = (nextConfig = {}, options = {}) => {
           'libsql',
           'require-in-the-middle',
         ],
+        plugins: [
+          ...(incomingWebpackConfig?.plugins || []),
+          // Fix cloudflare:sockets error: https://github.com/vercel/next.js/discussions/50177
+          new webpackOptions.webpack.IgnorePlugin({
+            resourceRegExp: /^pg-native$|^cloudflare:sockets$/,
+          }),
+        ],
         resolve: {
           ...(incomingWebpackConfig?.resolve || {}),
           alias: {
@@ -237,22 +202,31 @@ export const withPayload = (nextConfig = {}, options = {}) => {
             aws4: false,
           },
         },
-        plugins: [
-          ...(incomingWebpackConfig?.plugins || []),
-          // Fix cloudflare:sockets error: https://github.com/vercel/next.js/discussions/50177
-          new webpackOptions.webpack.IgnorePlugin({
-            resourceRegExp: /^pg-native$|^cloudflare:sockets$/,
-          }),
-        ],
       }
     },
   }
 
   if (nextConfig.basePath) {
-    toReturn.env.NEXT_BASE_PATH = nextConfig.basePath
+    baseConfig.env.NEXT_BASE_PATH = nextConfig.basePath
   }
 
-  return toReturn
+  if (!supportsTurbopackBuild) {
+    return withPayloadLegacy(baseConfig)
+  } else {
+    return {
+      ...baseConfig,
+      serverExternalPackages: [
+        ...(baseConfig.serverExternalPackages || []),
+        'drizzle-kit',
+        'drizzle-kit/api',
+        'sharp',
+        'libsql',
+        'require-in-the-middle',
+        // Prevents turbopack build errors by the thread-stream package which is installed by pino
+        'pino',
+      ],
+    }
+  }
 }
 
 export default withPayload