Skip to content

docs: update core documentation for Turbopack as default bundler #84282

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 11 commits into
base: graphite-base/84282
Choose a base branch
from
+83 −57
Open

docs: update core documentation for Turbopack as default bundler #84282

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
d634744
docs: update core documentation for Turbopack as default bundler
lukesandberg Sep 26, 2025
7a0ecf8
docs: update guides and migration docs for Turbopack as default
lukesandberg Sep 26, 2025
dffa53d
docs: update configuration and advanced topics for Turbopack default
lukesandberg Sep 26, 2025
20fd9e7
Update turbopack.mdx
lukesandberg Oct 2, 2025
fdd4939
Update turbopack.mdx
lukesandberg Oct 2, 2025
5ff5e08
Update local-development.mdx
lukesandberg Oct 2, 2025
3c828e8
Update from-create-react-app.mdx
lukesandberg Oct 2, 2025
d466d0f
Update 08-turbopack.mdx
lukesandberg Oct 2, 2025
6094278
review feedback
lukesandberg Oct 2, 2025
79b487d
document the webpack flag
lukesandberg Oct 3, 2025
8caef5e
Apply suggestions from code review
lukesandberg Oct 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/01-app/01-getting-started/01-installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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.

<AppOnly>

Expand Down
3 changes: 2 additions & 1 deletion docs/01-app/02-guides/custom-server.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
14 changes: 10 additions & 4 deletions docs/01-app/02-guides/local-development.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand Down
16 changes: 11 additions & 5 deletions docs/01-app/02-guides/migrating/from-create-react-app.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
Expand Down Expand Up @@ -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`:

Expand All @@ -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

Expand All @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions docs/01-app/03-api-reference/05-config/01-next-config-js/turbopack.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
55 changes: 28 additions & 27 deletions docs/01-app/03-api-reference/06-cli/create-next-app.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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 |
| `--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 <path-to-example>` | 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 <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 |
| `--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 <path-to-example>` | 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

Expand Down
6 changes: 4 additions & 2 deletions docs/01-app/03-api-reference/06-cli/next.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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. |
Expand Down Expand Up @@ -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). |
Expand Down
36 changes: 23 additions & 13 deletions docs/01-app/03-api-reference/08-turbopack.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.
Expand All @@ -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 |
Loading