Add --turbopack CLI flag (#71657)

timneutkens · wbinnssmith · web-flow · commit cfa003c7842e · 2024-10-22T22:31:05.000Z
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`  --------- Co-authored-by: Will Binns-Smith <wbinnssmith@gmail.com>
diff --git a/.github/actions/next-integration-stat/src/index.ts b/.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,
diff --git a/bench/heavy-npm-deps/package.json b/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",
diff --git a/crates/napi/src/turbopack.rs b/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>,
 
diff --git a/crates/next-core/src/mode.rs b/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,
diff --git a/docs/02-app/01-building-your-application/07-configuring/05-mdx.mdx b/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
 
diff --git a/docs/02-app/01-building-your-application/11-upgrading/05-from-create-react-app.mdx b/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
 
diff --git a/docs/02-app/02-api-reference/06-cli/create-next-app.mdx b/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  |
diff --git a/docs/02-app/02-api-reference/06-cli/next.mdx b/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.                                                                                |
diff --git a/docs/04-architecture/turbopack.mdx b/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.
diff --git a/packages/create-next-app/README.md b/packages/create-next-app/README.md
@@ -59,7 +59,7 @@ Options:
 
     Initialize inside a `src/` directory.
 
-  --turbo
+  --turbopack
 
     Enable Turbopack by default for development.
 
diff --git a/packages/create-next-app/create-app.ts b/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,
     })
   }
 
diff --git a/packages/create-next-app/index.ts b/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,
     })
   }
diff --git a/packages/create-next-app/templates/index.ts b/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",
diff --git a/packages/create-next-app/templates/types.ts b/packages/create-next-app/templates/types.ts
@@ -29,5 +29,5 @@ export interface InstallTemplateArgs {
   srcDir: boolean;
   importAlias: string;
   skipInstall: boolean;
-  turbo: boolean;
+  turbopack: boolean;
 }
diff --git a/packages/next-codemod/bin/upgrade.ts b/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 }
diff --git a/packages/next/src/bin/next.ts b/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>',
diff --git a/packages/next/src/cli/next-dev.ts b/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'
   }
 
diff --git a/packages/next/src/client/components/react-dev-overlay/internal/components/VersionStalenessInfo/VersionStalenessInfo.tsx b/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>
   )
 }
diff --git a/packages/next/src/lib/turbopack-warning.ts b/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',
diff --git a/packages/next/src/server/config-shared.ts b/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)
    */
diff --git a/packages/next/src/server/lib/app-info-log.ts b/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}`)
diff --git a/packages/next/src/server/next.ts b/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.
diff --git a/test/development/acceptance-app/version-staleness.test.ts b/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(
diff --git a/test/integration/create-next-app/index.test.ts b/test/integration/create-next-app/index.test.ts
diff --git a/test/integration/create-next-app/package-manager/bun.test.ts b/test/integration/create-next-app/package-manager/bun.test.ts
diff --git a/test/integration/create-next-app/package-manager/npm.test.ts b/test/integration/create-next-app/package-manager/npm.test.ts
diff --git a/test/integration/create-next-app/package-manager/pnpm.test.ts b/test/integration/create-next-app/package-manager/pnpm.test.ts
diff --git a/test/integration/create-next-app/package-manager/yarn.test.ts b/test/integration/create-next-app/package-manager/yarn.test.ts
diff --git a/test/integration/create-next-app/prompts.test.ts b/test/integration/create-next-app/prompts.test.ts
diff --git a/test/integration/create-next-app/templates/app.test.ts b/test/integration/create-next-app/templates/app.test.ts
diff --git a/test/integration/create-next-app/templates/matrix.test.ts b/test/integration/create-next-app/templates/matrix.test.ts
diff --git a/test/integration/create-next-app/templates/pages.test.ts b/test/integration/create-next-app/templates/pages.test.ts
diff --git a/test/integration/turbopack-unsupported-log/index.test.ts b/test/integration/turbopack-unsupported-log/index.test.ts

Original file line number	Diff line number	Diff line change
`@@ -735,7 +735,7 @@ const createCommentPostAsync =`
`735`	`735`	`console.log('Created a new comment', result.data.html_url)`
`736`	`736`	`}`
`737`	`737`
`738`		`-// An action report failed next.js integration test with --turbo`
	`738`	`+// An action report failed next.js integration test with --turbopack`
`739`	`739`	`async function run() {`
`740`	`740`	`const {`
`741`	`741`	`token,`
Original file line number	Diff line number	Diff line change
`@@ -784,7 +784,7 @@ module.exports = withMDX({`
`784`	`784`
`785`	`785`	`> Good to know:`
`786`	`786`	`>`
`787`		-> This option is required when processing markdown and MDX while using [Turbopack](/docs/architecture/turbopack) (`next dev --turbo`).
	`787`	+> This option is required when processing markdown and MDX while using [Turbopack](/docs/architecture/turbopack) (`next dev --turbopack`).
`788`	`788`
`789`	`789`	`## Helpful Links`
`790`	`790`