feat(next): add experimentalTurbopackBuild option

[robertjbass]

What?

Adds an experimentalTurbopackBuild option to withPayload() that allows users to bypass the Turbopack production build check introduced in #14696.

Why?

PR #14696 disabled Turbopack for production builds due to concerns about bundle size increases. However, some users may prefer the significantly faster build times Turbopack offers and are willing to accept the trade-off.

Build comparison on a real-world Payload project (Next.js 16, Payload 3.64.0):

Metric	Turbopack	Webpack	Difference
Compile time	9.1s	24.2s	Turbopack 2.6x faster
.next/server	888M	693M	Webpack 22% smaller
.next/static	11M	10M	~same

The server bundle is ~28% larger with Turbopack, but build times are significantly faster. This PR gives users the choice rather than blocking Turbopack entirely.

How?

• Added experimentalTurbopackBuild option to withPayload() options
• When true, bypasses the Turbopack build check
• Updated error message to inform users about the option
• JSDoc documents the option and notes that users may need to add packages to serverExternalPackages

Usage:

// next.config.mjs
export default withPayload(nextConfig, { experimentalTurbopackBuild: true })
// Users may also need to add the following to their next.config.mjs:
serverExternalPackages: [
  '@payloadcms/db-postgres', // or your database adapter
  '@payloadcms/drizzle',
  'drizzle-kit',
  'esbuild',
  'thread-stream',
],

Related:
PR: 14696
Issue: 14786

[ziggy-orbital]

Pleas :D

[abass]

We're aware this will be fixed in a future version of Next but it would be nice to be able to also stay on the latest versions of Payload while we wait on Vercel to allow the server dependencies too 🙏

[jonbarmby]

Agreed! Turbopack makes our CI/CD pipeline so much better.