Add --turbopack CLI flag (#71657)

Changes `--turbo` -> `--turbopack` to avoid confusion.

- Updated docs
- Updates create-next-app -- For create-next-app it's a rename as
otherwise there is an ordering problem with the prompts
- For the CLI `next dev --turbo` is still supported, will eventually be
a warning in a future version to swap with `--turbopack` but is not a
requirement today, can be handled automatically by the upgrade codemod
- New CLI flag: `next dev --turbopack`

<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:

## For Contributors

### Improving Documentation

- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide

### Adding or Updating Examples

- The "examples guidelines" are followed from our contributing doc
https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md
- Make sure the linting passes by running `pnpm build && pnpm lint`. See
https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md

### Fixing a bug

- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md

### Adding a feature

- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md


## For Maintainers

- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change

### What?

### Why?

### How?

Closes NEXT-
Fixes #

-->

---------

Co-authored-by: Will Binns-Smith <[email protected]>

.github/actions/next-integration-stat/src/index.ts

@@ -735,7 +735,7 @@ const createCommentPostAsync =
     console.log('Created a new comment', result.data.html_url)
   }
 
-// An action report failed next.js integration test with --turbo
+// An action report failed next.js integration test with --turbopack
 async function run() {
   const {
     token,

bench/heavy-npm-deps/package.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "dev-turbopack": "next dev --turbo",
+    "dev-turbopack": "next dev --turbopack",
     "dev-webpack": "next dev",
     "build-turbopack": "TURBOPACK=1 TURBOPACK_BUILD=1 next build",
     "build-webpack": "next build",

crates/napi/src/turbopack.rs

@@ -13,7 +13,7 @@ use crate::next_api::project::NapiDefineEnv;
 #[napi(object, object_to_js = false)]
 #[derive(Debug)]
 pub struct NextBuildContext {
-    // Added by Next.js for next build --turbo specifically.
+    // Added by Next.js for next build --turbopack specifically.
     /// The root directory of the workspace.
     pub root: Option<String>,
 

crates/next-core/src/mode.rs

@@ -6,7 +6,7 @@ use turbopack_ecmascript_runtime::RuntimeType;
 #[turbo_tasks::value(shared)]
 #[derive(Debug, Copy, Clone, TaskInput, Ord, PartialOrd, Hash)]
 pub enum NextMode {
-    /// `next dev --turbo`
+    /// `next dev --turbopack`
     Development,
     /// `next build`
     Build,

docs/02-app/01-building-your-application/07-configuring/05-mdx.mdx

@@ -784,7 +784,7 @@ module.exports = withMDX({
 
 > **Good to know**:
 >
-> This option is required when processing markdown and MDX while using [Turbopack](/docs/architecture/turbopack) (`next dev --turbo`).
+> This option is required when processing markdown and MDX while using [Turbopack](/docs/architecture/turbopack) (`next dev --turbopack`).
 
 ## Helpful Links
 

docs/02-app/01-building-your-application/11-upgrading/05-from-create-react-app.mdx

@@ -480,7 +480,7 @@ Create React App and Next.js both default to using webpack for bundling.
 
 When migrating your CRA application to Next.js, you might have a custom webpack configuration you're looking to migrate. Next.js supports providing a [custom webpack configuration](/docs/app/api-reference/next-config-js/webpack).
 
-Further, Next.js has support for [Turbopack](/docs/app/api-reference/next-config-js/turbo) through `next dev --turbo` to improve your local dev performance. Turbopack supports some [webpack loaders](/docs/app/api-reference/next-config-js/turbo) as well for compatibility and incremental adoption.
+Further, Next.js has support for [Turbopack](/docs/app/api-reference/next-config-js/turbo) through `next dev --turbopack` to improve your local dev performance. Turbopack supports some [webpack loaders](/docs/app/api-reference/next-config-js/turbo) as well for compatibility and incremental adoption.
 
 ## Next Steps
 

docs/02-app/02-api-reference/06-cli/create-next-app.mdx

@@ -28,7 +28,7 @@ The following options are available:
 | `--eslint`                              | Initialize with ESLint config                                   |
 | `--app`                                 | Initialize as an App Router project                             |
 | `--src-dir`                             | Initialize inside a `src/` directory                            |
-| `--turbo`                               | Enable Turbopack by default for development                     |
+| `--turbopack`                           | Enable Turbopack by default for development                     |
 | `--import-alias <alias-to-configure>`   | Specify import alias to use (default "@/\*")                    |
 | `--empty`                               | Initialize an empty project                                     |
 | `--use-npm`                             | Explicitly tell the CLI to bootstrap the application using npm  |

docs/02-app/02-api-reference/06-cli/next.mdx

@@ -45,7 +45,7 @@ The following commands are available:
 | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `-h, --help`                             | Show all available options.                                                                                                                          |
 | `[directory]`                            | A directory in which to build the application. If not provided, current directory is used.                                                           |
-| `--turbo`                                | Starts development mode using [Turbopack](https://nextjs.org/docs/architecture/turbopack).                                                           |
+| `--turbopack`                            | Starts development mode using [Turbopack](https://nextjs.org/docs/architecture/turbopack).                                                           |
 | `-p` or `--port <port>`                  | Specify a port number on which to start the application. Default: 3000, env: PORT                                                                    |
 | `-H`or `--hostname <hostname>`           | Specify a hostname on which to start the application. Useful for making the application available for other devices on the network. Default: 0.0.0.0 |
 | `--experimental-https`                   | Starts the server with HTTPS and generates a self-signed certificate.                                                                                |

docs/04-architecture/turbopack.mdx

@@ -7,12 +7,12 @@ description: Turbopack is an incremental bundler optimized for JavaScript and Ty
 
 ## Usage
 
-Turbopack can be used in Next.js in both the `pages` and `app` directories for faster local development. To enable Turbopack, use the `--turbo` flag when running the Next.js development server.
+Turbopack can be used in Next.js in both the `pages` and `app` directories for faster local development. To enable Turbopack, use the `--turbopack` flag when running the Next.js development server.
 
 ```json filename="package.json" highlight={3}
 {
   "scripts": {
-    "dev": "next dev --turbo",
+    "dev": "next dev --turbopack",
     "build": "next build",
     "start": "next start",
     "lint": "next lint"
@@ -76,6 +76,6 @@ These features are currently not supported:
 
 ## Generating Trace Files
 
-Trace files allow the Next.js team to investigate and improve performance metrics and memory usage. To generate a trace file, append `NEXT_TURBOPACK_TRACING=1` to the `next dev --turbo` command, this will generate a `.next/trace.log` file.
+Trace files allow the Next.js team to investigate and improve performance metrics and memory usage. To generate a trace file, append `NEXT_TURBOPACK_TRACING=1` to the `next dev --turbopack` command, this will generate a `.next/trace.log` file.
 
 When reporting issues related to Turbopack performance and memory usage, please include the trace file in your [GitHub](https://github.com/vercel/next.js) issue.

packages/create-next-app/README.md

@@ -59,7 +59,7 @@ Options:
 
     Initialize inside a `src/` directory.
 
-  --turbo
+  --turbopack
 
     Enable Turbopack by default for development.
 

packages/create-next-app/create-app.ts

@@ -36,7 +36,7 @@ export async function createApp({
   importAlias,
   skipInstall,
   empty,
-  turbo,
+  turbopack,
   disableGit,
 }: {
   appPath: string
@@ -51,7 +51,7 @@ export async function createApp({
   importAlias: string
   skipInstall: boolean
   empty: boolean
-  turbo: boolean
+  turbopack: boolean
   disableGit?: boolean
 }): Promise<void> {
   let repoInfo: RepoInfo | undefined
@@ -233,7 +233,7 @@ export async function createApp({
       srcDir,
       importAlias,
       skipInstall,
-      turbo,
+      turbopack,
     })
   }
 

packages/create-next-app/index.ts

@@ -52,7 +52,7 @@ const program = new Command(packageJson.name)
   .option('--eslint', 'Initialize with ESLint config.')
   .option('--app', 'Initialize as an App Router project.')
   .option('--src-dir', "Initialize inside a 'src/' directory.")
-  .option('--turbo', 'Enable Turbopack by default for development.')
+  .option('--turbopack', 'Enable Turbopack by default for development.')
   .option(
     '--import-alias <prefix/*>',
     'Specify import alias to use (default "@/*").'
@@ -233,7 +233,7 @@ async function run(): Promise<void> {
       importAlias: '@/*',
       customizeImportAlias: false,
       empty: false,
-      turbo: false,
+      turbopack: false,
       disableGit: false,
     }
     const getPrefOrDefault = (field: string) =>
@@ -351,22 +351,22 @@ async function run(): Promise<void> {
       }
     }
 
-    if (!opts.turbo && !args.includes('--no-turbo')) {
+    if (!opts.turbopack && !args.includes('--no-turbopack')) {
       if (skipPrompt) {
-        opts.turbo = getPrefOrDefault('turbo')
+        opts.turbopack = getPrefOrDefault('turbopack')
       } else {
         const styledTurbo = blue('Turbopack')
-        const { turbo } = await prompts({
+        const { turbopack } = await prompts({
           onState: onPromptState,
           type: 'toggle',
-          name: 'turbo',
+          name: 'turbopack',
           message: `Would you like to use ${styledTurbo} for ${`next dev`}?`,
-          initial: getPrefOrDefault('turbo'),
+          initial: getPrefOrDefault('turbopack'),
           active: 'Yes',
           inactive: 'No',
         })
-        opts.turbo = Boolean(turbo)
-        preferences.turbo = Boolean(turbo)
+        opts.turbopack = Boolean(turbopack)
+        preferences.turbopack = Boolean(turbopack)
       }
     }
 
@@ -429,7 +429,7 @@ async function run(): Promise<void> {
       importAlias: opts.importAlias,
       skipInstall: opts.skipInstall,
       empty: opts.empty,
-      turbo: opts.turbo,
+      turbopack: opts.turbopack,
       disableGit: opts.disableGit,
     })
   } catch (reason) {
@@ -461,7 +461,7 @@ async function run(): Promise<void> {
       importAlias: opts.importAlias,
       skipInstall: opts.skipInstall,
       empty: opts.empty,
-      turbo: opts.turbo,
+      turbopack: opts.turbopack,
       disableGit: opts.disableGit,
     })
   }

packages/create-next-app/templates/index.ts

@@ -43,7 +43,7 @@ export const installTemplate = async ({
   srcDir,
   importAlias,
   skipInstall,
-  turbo,
+  turbopack,
 }: InstallTemplateArgs) => {
   console.log(bold(`Using ${packageManager}.`));
 
@@ -188,7 +188,7 @@ export const installTemplate = async ({
     version: "0.1.0",
     private: true,
     scripts: {
-      dev: `next dev${turbo ? " --turbo" : ""}`,
+      dev: `next dev${turbopack ? " --turbopack" : ""}`,
       build: "next build",
       start: "next start",
       lint: "next lint",

packages/create-next-app/templates/types.ts

@@ -29,5 +29,5 @@ export interface InstallTemplateArgs {
   srcDir: boolean;
   importAlias: string;
   skipInstall: boolean;
-  turbo: boolean;
+  turbopack: boolean;
 }

packages/next-codemod/bin/upgrade.ts

@@ -403,16 +403,16 @@ function isUsingAppDir(projectPath: string): boolean {
  * Heuristics are used to determine whether to Turbopack is enabled or not and
  * to determine how to update the dev script.
  *
- * 1. If the dev script contains `--turbo` option, we assume that Turbopack is
+ * 1. If the dev script contains `--turbopack` option, we assume that Turbopack is
  *    already enabled.
  * 2. If the dev script contains the string `next dev`, we replace it to
- *    `next dev --turbo`.
- * 3. Otherwise, we ask the user to manually add `--turbo` to their dev command,
+ *    `next dev --turbopack`.
+ * 3. Otherwise, we ask the user to manually add `--turbopack` to their dev command,
  *    showing the current dev command as the initial value.
  */
 async function suggestTurbopack(packageJson: any): Promise<void> {
   const devScript: string = packageJson.scripts['dev']
-  if (devScript.includes('--turbo')) return
+  if (devScript.includes('--turbopack')) return
 
   const responseTurbopack = await prompts(
     {
@@ -431,7 +431,7 @@ async function suggestTurbopack(packageJson: any): Promise<void> {
   if (devScript.includes('next dev')) {
     packageJson.scripts['dev'] = devScript.replace(
       'next dev',
-      'next dev --turbo'
+      'next dev --turbopack'
     )
     return
   }
@@ -444,7 +444,7 @@ async function suggestTurbopack(packageJson: any): Promise<void> {
     {
       type: 'text',
       name: 'customDevScript',
-      message: 'Please manually add "--turbo" to your dev command.',
+      message: 'Please manually add "--turbopack" to your dev command.',
       initial: devScript,
     },
     { onCancel }

packages/next/src/bin/next.ts

@@ -157,7 +157,8 @@ program
       'If no directory is provided, the current directory will be used.'
     )}`
   )
-  .option('--turbo', 'Starts development mode using Turbopack (beta).')
+  .option('--turbo', 'Starts development mode using Turbopack.')
+  .option('--turbopack', 'Starts development mode using Turbopack.')
   .addOption(
     new Option(
       '-p, --port <port>',

packages/next/src/cli/next-dev.ts

@@ -40,6 +40,7 @@ import { flushAllTraces, trace } from '../trace'
 
 export type NextDevOptions = {
   turbo?: boolean
+  turbopack?: boolean
   port: number
   hostname?: string
   experimentalHttps?: boolean
@@ -232,7 +233,7 @@ const nextDev = async (
     hostname: host,
   }
 
-  if (options.turbo) {
+  if (options.turbo || options.turbopack) {
     process.env.TURBOPACK = '1'
   }
 

packages/next/src/client/components/react-dev-overlay/internal/components/VersionStalenessInfo/VersionStalenessInfo.tsx

@@ -28,7 +28,7 @@ export function VersionStalenessInfo({
           (learn more)
         </a>
       )}
-      {process.env.TURBOPACK ? ' (turbo)' : ''}
+      {process.env.TURBOPACK ? ' (Turbopack)' : ''}
     </span>
   )
 }

packages/next/src/lib/turbopack-warning.ts

@@ -47,7 +47,7 @@ const unsupportedTurbopackNextConfigOptions = [
   'experimental.urlImports',
 ]
 
-// The following will need to be supported by `next build --turbo`
+// The following will need to be supported by `next build --turbopack`
 const unsupportedProductionSpecificTurbopackNextConfigOptions: string[] = [
   // TODO: Support disabling sourcemaps, currently they're always enabled.
   // 'productionBrowserSourceMaps',

packages/next/src/server/config-shared.ts

@@ -115,7 +115,7 @@ export type TurboRuleConfigItem =
 
 export interface ExperimentalTurboOptions {
   /**
-   * (`next --turbo` only) A mapping of aliased imports to modules to load in their place.
+   * (`next --turbopack` only) A mapping of aliased imports to modules to load in their place.
    *
    * @see [Resolve Alias](https://nextjs.org/docs/app/api-reference/next-config-js/turbo#resolve-alias)
    */
@@ -125,21 +125,21 @@ export interface ExperimentalTurboOptions {
   >
 
   /**
-   * (`next --turbo` only) A list of extensions to resolve when importing files.
+   * (`next --turbopack` only) A list of extensions to resolve when importing files.
    *
    * @see [Resolve Extensions](https://nextjs.org/docs/app/api-reference/next-config-js/turbo#resolve-extensions)
    */
   resolveExtensions?: string[]
 
   /**
-   * (`next --turbo` only) A list of webpack loaders to apply when running with Turbopack.
+   * (`next --turbopack` only) A list of webpack loaders to apply when running with Turbopack.
    *
    * @see [Turbopack Loaders](https://nextjs.org/docs/app/api-reference/next-config-js/turbo#webpack-loaders)
    */
   loaders?: Record<string, TurboLoaderItem[]>
 
   /**
-   * (`next --turbo` only) A list of webpack loaders to apply when running with Turbopack.
+   * (`next --turbopack` only) A list of webpack loaders to apply when running with Turbopack.
    *
    * @see [Turbopack Loaders](https://nextjs.org/docs/app/api-reference/next-config-js/turbo#webpack-loaders)
    */

packages/next/src/server/lib/app-info-log.ts

@@ -23,7 +23,7 @@ export function logStartInfo({
   Log.bootstrap(
     `${bold(
       purple(`${Log.prefixes.ready} Next.js ${process.env.__NEXT_VERSION}`)
-    )}${process.env.TURBOPACK ? ' (turbo)' : ''}`
+    )}${process.env.TURBOPACK ? ' (Turbopack)' : ''}`
   )
   if (appUrl) {
     Log.bootstrap(`- Local:        ${appUrl}`)

packages/next/src/server/next.ts

@@ -354,9 +354,10 @@ class NextCustomServer extends NextServer {
 function createServer(
   options: NextServerOptions & {
     turbo?: boolean
+    turbopack?: boolean
   }
 ): NextServer {
-  if (options && options.turbo) {
+  if (options && (options.turbo || options.turbopack)) {
     process.env.TURBOPACK = '1'
   }
   // The package is used as a TypeScript plugin.

test/development/acceptance-app/version-staleness.test.ts

@@ -49,7 +49,7 @@ describe('Error Overlay version staleness', () => {
 
     if (process.env.TURBOPACK) {
       expect(await getStaleness(browser)).toMatchInlineSnapshot(
-        `"Next.js (1.0.0) is outdated (learn more) (turbo)"`
+        `"Next.js (1.0.0) is outdated (learn more) (Turbopack)"`
       )
     } else {
       expect(await getStaleness(browser)).toMatchInlineSnapshot(
@@ -86,7 +86,7 @@ describe('Error Overlay version staleness', () => {
 
     if (process.env.TURBOPACK) {
       expect(await getStaleness(browser)).toMatchInlineSnapshot(
-        `"Next.js (2.0.0) is outdated (learn more) (turbo)"`
+        `"Next.js (2.0.0) is outdated (learn more) (Turbopack)"`
       )
     } else {
       expect(await getStaleness(browser)).toMatchInlineSnapshot(
@@ -120,7 +120,7 @@ describe('Error Overlay version staleness', () => {
 
     if (process.env.TURBOPACK) {
       expect(await getStaleness(browser)).toMatchInlineSnapshot(
-        `"Next.js (3.0.0) is outdated (learn more) (turbo)"`
+        `"Next.js (3.0.0) is outdated (learn more) (Turbopack)"`
       )
     } else {
       expect(await getStaleness(browser)).toMatchInlineSnapshot(