Add a --webpack flag and default --turbopack to true

[lukesandberg]

Make Turbopack the default bundler for Next 🚀

What

Add a --webpack flag so users can select webpack

Change behavior so if neither --turbopack or --webpack is set we default to Turbopack.

If we have defaulted the build to turbopack and we observe that the user has a webpack config in their next config but no turbopack config, then we issue a warning about this being a potential problem, if this happens during next build the warning becomes an error and fails the build. The solution for users is just to explicitly set --webpack or --turbopack

There were a number of subtle issues

• some users directly set the TURBOPACK environment variable, this PR adds support for that though users should really be passing --turbopack so it will not be documented
• rspack is enabled via a plugin that sets an environment variable when loading next config, which means it happens way too late!
  • For builds this isn't too bad, we just have to recompute the Bundler after loading the config. For dev the parent process can get out of sync with the child, but this is only really relevant for telemetry and for that we already load the config in the parent so just defer computing isTurboSession.

Most of this is about fixing package.json scripts and CI builds configs.

• For package.json

  • i added aliases e.g. test-dev == test-dev-webpack but preserved the old names. In the long run we will want to remove the unsuffixed aliases
  • this required some modifications to existing configs to ensure everything was setting the correct env variables

• For ci, i added a new IS_WEBPACK_TEST variable to a number of tests but preserved all names.

  • Again, in the future it would make sense to rename ci jobs but that is deferred for right now.
  • This also makes it clear that a set of tests scenarios (e.g. ppr, experimental, test-new-tests-*) never run with turbopack. This is not addressed right now but should be in the future.

Why

Today, the default bundler for next is webpack but with turbopack becoming stable it is time to just ship it. Turbopack is already recommended for dev and builds. Create Next App also steers users towards Turbopack. According to telemetry we already have about 50% of all dev sessions and build adoption is growing. So fundamentally why are we even asking users to make a decision?

Closes PACK-5588

[lukesandberg]

• Make turbopack the default bundler for custom servers #84281 : 2 dependent PRs (#84300 , #84476 )
• Add a --webpack flag and default --turbopack to true #84216 👈 (View in Graphite)
• canary

This stack of pull requests is managed by Graphite. Learn more about stacking.

[ijjk]

Tests Passed

[bgw]

[lukesandberg]

[vercel]

Additional Comments:

packages/next/src/server/next.ts (lines 541-543):

The server creation logic uses outdated bundler detection that bypasses the new centralized parseBundlerArgs function, creating inconsistent behavior between CLI and programmatic usage.

View Details

📝 Patch Details

diff --git a/packages/next/src/server/next.ts b/packages/next/src/server/next.ts
index 88de1cd32a..d3b68ab21e 100644
--- a/packages/next/src/server/next.ts
+++ b/packages/next/src/server/next.ts
@@ -31,6 +31,7 @@ import {
   RouterServerContextSymbol,
   routerServerGlobal,
 } from './lib/router-utils/router-server-context'
+import { parseBundlerArgs } from '../lib/bundler'
 
 let ServerImpl: typeof NextNodeServer
 
@@ -534,13 +535,16 @@ function createServer(
   options: NextServerOptions & {
     turbo?: boolean
     turbopack?: boolean
+    webpack?: boolean
   }
 ): NextWrapperServer {
-  if (
-    options &&
-    (options.turbo || options.turbopack || process.env.IS_TURBOPACK_TEST)
-  ) {
-    process.env.TURBOPACK = '1'
+  if (options) {
+    // Use centralized bundler argument parsing for consistency with CLI usage
+    parseBundlerArgs({
+      turbo: options.turbo,
+      turbopack: options.turbopack,
+      webpack: options.webpack,
+    })
   }
   // The package is used as a TypeScript plugin.
   if (

Analysis

Inconsistent bundler detection between CLI and programmatic usage

What fails: createServer() in packages/next/src/server/next.ts uses outdated bundler detection logic that bypasses the centralized parseBundlerArgs() function, creating inconsistent behavior between CLI and programmatic usage.

How to reproduce:

// CLI usage (via next-dev.ts) - uses parseBundlerArgs with full feature set
const bundler = parseBundlerArgs({ webpack: true }); // Returns Webpack, no TURBOPACK env set

// Programmatic usage (via createServer) - uses old logic  
const server = createServer({ webpack: true }); // Ignores webpack flag completely

Result: CLI usage supports --webpack flag and conflict detection, while programmatic usage ignores --webpack and has no conflict detection. parseBundlerArgs sets TURBOPACK='auto' for defaults and uses ??= '1' for explicit flags, while createServer always sets TURBOPACK='1'.

Expected: Both CLI and programmatic usage should use the same centralized parseBundlerArgs() function for consistent bundler selection behavior.

[vercel]

Suggested change

	`NEXT_TEST_USE_RSPACK=${process.env.NEXT_TEST_USE_RSPACK}`
	`IS_RSPACK_TEST=${process.env.IS_RSPACK_TEST}`

The Rspack test environment variable check uses the wrong variable name in the error message string, causing incorrect debug output.

View Details

Analysis

Incorrect environment variable in Rspack test condition debug message

What fails: parseBundlerArgs() in packages/next/src/lib/bundler.ts checks process.env.IS_RSPACK_TEST but displays process.env.NEXT_TEST_USE_RSPACK value in error messages, causing misleading debug output

How to reproduce:

# Set IS_RSPACK_TEST without NEXT_TEST_USE_RSPACK
IS_RSPACK_TEST=true node -e "console.log('Debug will show: NEXT_TEST_USE_RSPACK=undefined')"

Result: When IS_RSPACK_TEST=true but NEXT_TEST_USE_RSPACK is undefined, debug output shows misleading NEXT_TEST_USE_RSPACK=undefined instead of IS_RSPACK_TEST=true

Expected: Debug message should match the condition variable like other patterns in the same file:

• IS_TURBOPACK_TEST → IS_TURBOPACK_TEST=
• IS_WEBPACK_TEST → IS_WEBPACK_TEST=
• IS_RSPACK_TEST should → IS_RSPACK_TEST=

[lukesandberg]

good catch by vade, this will go in the next PR. Using the same function is not quite practical but close.

[lukesandberg]

Merge activity

• Sep 26, 11:24 PM UTC: @lukesandberg merged this pull request with Graphite.