diff --git a/docs/01-app/01-getting-started/01-installation.mdx b/docs/01-app/01-getting-started/01-installation.mdx index 3e7772bfca6633..14c00e6f4cf109 100644 --- a/docs/01-app/01-getting-started/01-installation.mdx +++ b/docs/01-app/01-getting-started/01-installation.mdx @@ -101,7 +101,7 @@ Then, add the following scripts to your `package.json` file: ```json filename="package.json" { "scripts": { - "dev": "next dev --turbopack", + "dev": "next dev", "build": "next build", "start": "next start", "lint": "eslint", @@ -112,12 +112,12 @@ Then, add the following scripts to your `package.json` file: These scripts refer to the different stages of developing an application: -- `next dev --turbopack`: Starts the development server using Turbopack. +- `next dev`: Starts the development server using Turbopack (default bundler). - `next build`: Builds the application for production. - `next start`: Starts the production server. - `eslint`: Runs ESLint. -Turbopack is stable for `dev`. For production builds, Turbopack is in beta. To try it, run `next build --turbopack`. See the [Turbopack docs](/docs/app/api-reference/turbopack) for status and caveats. +Turbopack is now the default bundler. To use Webpack run `next dev --webpack` or `next build --webpack`. See the [Turbopack docs](/docs/app/api-reference/turbopack) for configuration details. diff --git a/docs/01-app/02-guides/custom-server.mdx b/docs/01-app/02-guides/custom-server.mdx index 85842910090f31..09ca9716348775 100644 --- a/docs/01-app/02-guides/custom-server.mdx +++ b/docs/01-app/02-guides/custom-server.mdx @@ -96,7 +96,8 @@ The above `next` import is a function that receives an object with the following | `hostname` | `String` | (_Optional_) The hostname the server is running behind | | `port` | `Number` | (_Optional_) The port the server is running behind | | `httpServer` | `node:http#Server` | (_Optional_) The HTTP Server that Next.js is running behind | -| `turbo` | `Boolean` | (_Optional_) Enable Turbopack | +| `turbopack` | `Boolean` | (_Optional_) Enable Turbopack (enabled by default) | +| `webpack` | `Boolean` | (_Optional_) Enable webpack | The returned `app` can then be used to let Next.js handle requests as required. diff --git a/docs/01-app/02-guides/local-development.mdx b/docs/01-app/02-guides/local-development.mdx index df881aa18cd52c..4f12dd7b9cada8 100644 --- a/docs/01-app/02-guides/local-development.mdx +++ b/docs/01-app/02-guides/local-development.mdx @@ -48,15 +48,21 @@ On macOS, you can disable [Gatekeeper](https://support.apple.com/guide/security/ If you or your employer have configured any other Antivirus solutions on your system, you should inspect the relevant settings for those products. -### 2. Update Next.js and enable Turbopack +### 2. Update Next.js and use Turbopack Make sure you're using the latest version of Next.js. Each new version often includes performance improvements. -Turbopack is a new bundler integrated into Next.js that can improve local performance. +Turbopack is now the default bundler for Next.js development and provides significant performance improvements over webpack. ```bash npm install next@latest -npm run dev --turbopack +npm run dev # Turbopack is used by default +``` + +If you need to use Webpack instead of Turbopack, you can opt-in: + +```bash +npm run dev --webpack ``` [Learn more about Turbopack](/blog/turbopack-for-development-stable). See our [upgrade guides](/docs/app/guides/upgrading) and codemods for more information. @@ -146,7 +152,7 @@ Tailwind CSS version 3.4.8 or newer will warn you about settings that might slow If you've added custom webpack settings, they might be slowing down compilation. -Consider if you really need them for local development. You can optionally only include certain tools for production builds, or explore moving to Turbopack and using [loaders](/docs/app/api-reference/config/next-config-js/turbopack#supported-loaders). +Consider if you really need them for local development. You can optionally only include certain tools for production builds, or explore using the default Turbopack bundler and configuring [loaders](/docs/app/api-reference/config/next-config-js/turbopack#configuring-webpack-loaders) instead. ### 6. Optimize memory usage diff --git a/docs/01-app/02-guides/migrating/from-create-react-app.mdx b/docs/01-app/02-guides/migrating/from-create-react-app.mdx index 1a0445d878950f..79854145277a8e 100644 --- a/docs/01-app/02-guides/migrating/from-create-react-app.mdx +++ b/docs/01-app/02-guides/migrating/from-create-react-app.mdx @@ -455,7 +455,7 @@ Update your `package.json` scripts to use Next.js commands. Also, add `.next` an ```json filename="package.json" { "scripts": { - "dev": "next dev --turbopack", + "dev": "next dev", "build": "next build", "start": "npx serve@latest ./build" } @@ -526,7 +526,7 @@ const nextConfig: NextConfig = { } ``` -### Custom Webpack / Babel Config +### Custom Webpack If you had a custom webpack or Babel configuration in CRA, you can extend Next.js’s config in `next.config.ts`: @@ -543,7 +543,7 @@ const nextConfig: NextConfig = { export default nextConfig ``` -> **Note**: This will require disabling Turbopack by removing `--turbopack` from your `dev` script. +> **Note**: This will require using Webpack by adding `--webpack` to your `dev` script. ### TypeScript Setup @@ -557,10 +557,16 @@ Next.js automatically sets up TypeScript if you have a `tsconfig.json`. Make sur ## Bundler Compatibility -Both Create React App and Next.js default to webpack for bundling. Next.js also offers [Turbopack](/docs/app/api-reference/config/next-config-js/turbopack) for faster local development with: +Create React App uses webpack for bundling. Next.js now defaults to [Turbopack](/docs/app/api-reference/config/next-config-js/turbopack) for faster local development: ```bash -next dev --turbopack +next dev # Uses Turbopack by default +``` + +To use Webpack instead (similar to CRA): + +```bash +next dev --webpack ``` You can still provide a [custom webpack configuration](/docs/app/api-reference/config/next-config-js/webpack) if you need to migrate advanced webpack settings from CRA. diff --git a/docs/01-app/03-api-reference/05-config/01-next-config-js/turbopack.mdx b/docs/01-app/03-api-reference/05-config/01-next-config-js/turbopack.mdx index dd2a2aec8c0a42..44df82763d674c 100644 --- a/docs/01-app/03-api-reference/05-config/01-next-config-js/turbopack.mdx +++ b/docs/01-app/03-api-reference/05-config/01-next-config-js/turbopack.mdx @@ -186,8 +186,8 @@ In addition, a number of built-in conditions are supported: - `browser`: Matches code that will execute on the client. Server code can be matched using `{not: 'browser'}`. - `foreign`: Matches code in `node_modules`, as well as some Next.js internals. Usually you'll want to restrict loaders to `{not: 'foreign'}`. This can improve performance by reducing the number of files the loader is invoked on. -- `development`: Matches when using `next dev --turbopack`. -- `production`: Matches when using `next build --turbopack`. +- `development`: Matches when using `next dev`. +- `production`: Matches when using `next build`. - `node`: Matches code that will run on the default Node.js runtime. - `edge-light`: Matches code that will run on the [Edge runtime](/docs/app/api-reference/edge). diff --git a/docs/01-app/03-api-reference/06-cli/create-next-app.mdx b/docs/01-app/03-api-reference/06-cli/create-next-app.mdx index dbd5765edc0ee3..4f537c2880466f 100644 --- a/docs/01-app/03-api-reference/06-cli/create-next-app.mdx +++ b/docs/01-app/03-api-reference/06-cli/create-next-app.mdx @@ -17,33 +17,34 @@ npx create-next-app@latest [project-name] [options] The following options are available: -| Options | Description | -| --------------------------------------- | --------------------------------------------------------------- | -| `-h` or `--help` | Show all available options | -| `-v` or `--version` | Output the version number | -| `--no-*` | Negate default options. E.g. `--no-ts` | -| `--ts` or `--typescript` | Initialize as a TypeScript project (default) | -| `--js` or `--javascript` | Initialize as a JavaScript project | -| `--tailwind` | Initialize with Tailwind CSS config (default) | -| `--eslint` | Initialize with ESLint config | -| `--biome` | Initialize with Biome config | -| `--no-linter` | Skip linter configuration | -| `--app` | Initialize as an App Router project | -| `--api` | Initialize a project with only route handlers | -| `--src-dir` | Initialize inside a `src/` directory | -| `--turbopack` | Enable Turbopack by default for development | -| `--import-alias ` | Specify import alias to use (default "@/\*") | -| `--empty` | Initialize an empty project | -| `--use-npm` | Explicitly tell the CLI to bootstrap the application using npm | -| `--use-pnpm` | Explicitly tell the CLI to bootstrap the application using pnpm | -| `--use-yarn` | Explicitly tell the CLI to bootstrap the application using Yarn | -| `--use-bun` | Explicitly tell the CLI to bootstrap the application using Bun | -| `-e` or `--example [name] [github-url]` | An example to bootstrap the app with | -| `--example-path ` | Specify the path to the example separately | -| `--reset-preferences` | Explicitly tell the CLI to reset any stored preferences | -| `--skip-install` | Explicitly tell the CLI to skip installing packages | -| `--disable-git` | Explicitly tell the CLI to disable git initialization | -| `--yes` | Use previous preferences or defaults for all options | +| Options | Description | +| --------------------------------------- | --------------------------------------------------------------------- | +| `-h` or `--help` | Show all available options | +| `-v` or `--version` | Output the version number | +| `--no-*` | Negate default options. E.g. `--no-ts` | +| `--ts` or `--typescript` | Initialize as a TypeScript project (default) | +| `--js` or `--javascript` | Initialize as a JavaScript project | +| `--tailwind` | Initialize with Tailwind CSS config (default) | +| `--eslint` | Initialize with ESLint config | +| `--biome` | Initialize with Biome config | +| `--no-linter` | Skip linter configuration | +| `--app` | Initialize as an App Router project | +| `--api` | Initialize a project with only route handlers | +| `--src-dir` | Initialize inside a `src/` directory | +| `--turbopack` | Force enable Turbopack in generated package.json (enabled by default) | +| `--webpack` | Force enable Webpack in generated package.json | +| `--import-alias ` | Specify import alias to use (default "@/\*") | +| `--empty` | Initialize an empty project | +| `--use-npm` | Explicitly tell the CLI to bootstrap the application using npm | +| `--use-pnpm` | Explicitly tell the CLI to bootstrap the application using pnpm | +| `--use-yarn` | Explicitly tell the CLI to bootstrap the application using Yarn | +| `--use-bun` | Explicitly tell the CLI to bootstrap the application using Bun | +| `-e` or `--example [name] [github-url]` | An example to bootstrap the app with | +| `--example-path ` | Specify the path to the example separately | +| `--reset-preferences` | Explicitly tell the CLI to reset any stored preferences | +| `--skip-install` | Explicitly tell the CLI to skip installing packages | +| `--disable-git` | Explicitly tell the CLI to disable git initialization | +| `--yes` | Use previous preferences or defaults for all options | ## Examples diff --git a/docs/01-app/03-api-reference/06-cli/next.mdx b/docs/01-app/03-api-reference/06-cli/next.mdx index 0ce8e56db1d02a..7b20848c389af5 100644 --- a/docs/01-app/03-api-reference/06-cli/next.mdx +++ b/docs/01-app/03-api-reference/06-cli/next.mdx @@ -46,7 +46,8 @@ 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. | -| `--turbopack` | Starts development mode using [Turbopack](/docs/app/api-reference/turbopack). Also available as `--turbo`. | +| `--turbopack` | Force enable [Turbopack](/docs/app/api-reference/turbopack) (enabled by default). Also available as `--turbo`. | +| `--webpack` | Use Webpack instead of the default [Turbopack](/docs/app/api-reference/turbopack) bundler for development. | | `-p` or `--port ` | Specify a port number on which to start the application. Default: 3000, env: PORT | | `-H`or `--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. | @@ -74,7 +75,8 @@ The following options are available for the `next build` command: | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-h, --help` | Show all available options. | | `[directory]` | A directory on which to build the application. If not provided, the current directory will be used. | -| `--turbopack` | Build using [Turbopack](/docs/app/api-reference/turbopack) (beta). Also available as `--turbo`. | +| `--turbopack` | Force enable [Turbopack](/docs/app/api-reference/turbopack) (enabled by default). Also available as `--turbo`. | +| `--webpack` | Build using Webpack. | | `-d` or `--debug` | Enables a more verbose build output. With this flag enabled additional build output like rewrites, redirects, and headers will be shown. | | | | `--profile` | Enables production [profiling for React](https://react.dev/reference/react/Profiler). | diff --git a/docs/01-app/03-api-reference/08-turbopack.mdx b/docs/01-app/03-api-reference/08-turbopack.mdx index ae72991968279e..b23c0b7868e939 100644 --- a/docs/01-app/03-api-reference/08-turbopack.mdx +++ b/docs/01-app/03-api-reference/08-turbopack.mdx @@ -18,19 +18,31 @@ We built Turbopack to push the performance of Next.js, including: ## Getting started -To enable Turbopack in your Next.js project, add the `--turbopack` flag to the `dev` and `build` scripts in your `package.json` file: +Turbopack is now the **default bundler** in Next.js. No configuration is needed to use Turbopack: ```json filename="package.json" highlight={3} { "scripts": { - "dev": "next dev --turbopack", - "build": "next build --turbopack", + "dev": "next dev", + "build": "next build", "start": "next start" } } ``` -Currently, Turbopack for `dev` is stable, while `build` is in beta. We are actively working on production support as Turbopack moves closer to stability. +### Using Webpack instead + +If you need to use Webpack instead of Turbopack, you can opt-in with the `--webpack` flag: + +```json filename="package.json" +{ + "scripts": { + "dev": "next dev --webpack", + "build": "next build --webpack", + "start": "next start" + } +} +``` ## Supported features @@ -204,7 +216,7 @@ For more in-depth configuration examples, see the [Turbopack config documentatio If you encounter performance or memory issues and want to help the Next.js team diagnose them, you can generate a trace file by appending `NEXT_TURBOPACK_TRACING=1` to your dev command: ```bash -NEXT_TURBOPACK_TRACING=1 next dev --turbopack +NEXT_TURBOPACK_TRACING=1 next dev ``` This will produce a `.next/trace-turbopack` file. Include that file when creating a GitHub issue on the [Next.js repo](https://github.com/vercel/next.js) to help us investigate. @@ -213,13 +225,11 @@ This will produce a `.next/trace-turbopack` file. Include that file when creatin Turbopack is a **Rust-based**, **incremental** bundler designed to make local development and builds fast—especially for large applications. It is integrated into Next.js, offering zero-config CSS, React, and TypeScript support. -Stay tuned for more updates as we continue to improve Turbopack and add production build support. In the meantime, give it a try with `next dev --turbopack` and let us know your feedback. - ## Version Changes -| Version | Changes | -| --------- | -------------------------------------------------------------- | -| `v16.0.0` | Automatic support for Babel when a configuration file is found | -| `v15.5.0` | Turbopack support for `build` beta | -| `v15.3.0` | Experimental support for `build` | -| `v15.0.0` | Turbopack for `dev` stable | +| Version | Changes | +| --------- | ----------------------------------------------------------------------------------------------------------------- | +| `v16.0.0` | Turbopack becomes the default bundler for Next.js. Automatic support for Babel when a configuration file is found | +| `v15.5.0` | Turbopack support for `build` beta | +| `v15.3.0` | Experimental support for `build` | +| `v15.0.0` | Turbopack for `dev` stable |