Skip to content

Turbopack: update docs for config.turbopack #77853

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

Merged
merged 3 commits into from
Apr 9, 2025
Merged

Turbopack: update docs for config.turbopack #77853

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
01ede8a
Turbopack: update docs for `config.turbopack`
wbinnssmith Apr 5, 2025
460bbd3
Document `root` option
timneutkens Apr 9, 2025
4fcfdcc
Remove moduleIds docs
timneutkens Apr 9, 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
2 changes: 1 addition & 1 deletion docs/01-app/03-building-your-application/06-optimizing/14-local-development.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,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/turbo#supported-loaders).
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).

### 6. Optimize memory usage

Expand Down
2 changes: 1 addition & 1 deletion docs/01-app/03-building-your-application/11-upgrading/06-from-create-react-app.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -557,7 +557,7 @@ 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/turbo) for faster local development with:
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:

```bash
next dev --turbopack
Expand Down
106 changes: 45 additions & 61 deletions ...nce/05-config/01-next-config-js/turbo.mdx → ...05-config/01-next-config-js/turbopack.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,18 @@
---
title: turbo
title: turbopack
description: Configure Next.js with Turbopack-specific options
version: experimental
---

{/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}

The `turbo` option lets you customize [Turbopack](/docs/app/api-reference/turbopack) to transform different files and change how modules are resolved.
The `turbopack` option lets you customize [Turbopack](/docs/app/api-reference/turbopack) to transform different files and change how modules are resolved.

```ts filename="next.config.ts" switcher
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
experimental: {
turbo: {
// ...
},
turbopack: {
// ...
},
}

Expand All @@ -25,10 +22,8 @@ export default nextConfig
```js filename="next.config.js" switcher
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
turbo: {
// ...
},
turbopack: {
// ...
},
}

Expand All @@ -47,12 +42,10 @@ The following options are available for the `turbo` configuration:

| Option | Description |
| ------------------- | ----------------------------------------------------------------------- |
| `root` | Sets the application root directory. Should be an absolute path. |
| `rules` | List of supported webpack loaders to apply when running with Turbopack. |
| `resolveAlias` | Map aliased imports to modules to load in their place. |
| `resolveExtensions` | List of extensions to resolve when importing files. |
| `moduleIds` | Assign module IDs |
| `treeShaking` | Enable tree shaking for the turbopack dev server and build. |
| `memoryLimit` | A target memory limit for turbo, in bytes. |

### Supported loaders

Expand All @@ -68,6 +61,29 @@ The following loaders have been tested to work with Turbopack's webpack loader i

## Examples

### Root directory

Turbopack uses the root directory to resolve modules. Files outside of the project root are not resolved.

Next.js automatically detects the root directory of your project. It does so by looking for one of these files:

- `pnpm-lock.yaml`
- `package-lock.json`
- `yarn.lock`
- `bun.lock`
- `bun.lockb`

If you have a different project structure, for example if you don't use workspaces, you can manually set the `root` option:

```js filename="next.config.js"
const path = require('path')
module.exports = {
turbopack: {
root: path.join(__dirname, '..'),
},
}
```

### Configuring webpack loaders

If you need loader support beyond what's built in, many webpack loaders already work with Turbopack. There are currently some limitations:
Expand All @@ -82,13 +98,11 @@ Here is an example below using the [`@svgr/webpack`](https://www.npmjs.com/packa

```js filename="next.config.js"
module.exports = {
experimental: {
turbo: {
rules: {
'*.svg': {
loaders: ['@svgr/webpack'],
as: '*.js',
},
turbopack: {
rules: {
'*.svg': {
loaders: ['@svgr/webpack'],
as: '*.js',
},
},
},
Expand All @@ -105,12 +119,10 @@ To configure resolve aliases, map imported patterns to their new destination in

```js filename="next.config.js"
module.exports = {
experimental: {
turbo: {
resolveAlias: {
underscore: 'lodash',
mocha: { browser: 'mocha/browser-entry.js' },
},
turbopack: {
resolveAlias: {
underscore: 'lodash',
mocha: { browser: 'mocha/browser-entry.js' },
},
},
}
Expand All @@ -128,18 +140,8 @@ To configure resolve extensions, use the `resolveExtensions` field in `next.conf

```js filename="next.config.js"
module.exports = {
experimental: {
turbo: {
resolveExtensions: [
'.mdx',
'.tsx',
'.ts',
'.jsx',
'.js',
'.mjs',
'.json',
],
},
turbopack: {
resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.json'],
},
}
```
Expand All @@ -148,27 +150,9 @@ This overwrites the original resolve extensions with the provided list. Make sur

For more information and guidance for how to migrate your app to Turbopack from webpack, see [Turbopack's documentation on webpack compatibility](https://turbo.build/pack/docs/migrating-from-webpack).

### Assigning module IDs

Turbopack currently supports two strategies for assigning module IDs:

- `'named'` assigns readable module IDs based on the module's path and functionality.
- `'deterministic'` assigns small hashed numeric module IDs, which are mostly consistent between builds and therefore help with long-term caching.

If not set, Turbopack will use `'named'` for development builds and `'deterministic'` for production builds.

To configure the module IDs strategy, use the `moduleIds` field in `next.config.js`:

```js filename="next.config.js"
module.exports = {
turbo: {
moduleIds: 'deterministic',
},
}
```

## Version History

| Version | Changes |
| -------- | -------------------------------- |
| `13.0.0` | `experimental.turbo` introduced. |
| Version | Changes |
| -------- | ----------------------------------------------- |
| `15.3.0` | `experimental.turbo` is changed to `turbopack`. |
| `13.0.0` | `experimental.turbo` introduced. |
48 changes: 23 additions & 25 deletions docs/01-app/05-api-reference/08-turbopack.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,13 @@ Turbopack in Next.js has **zero-configuration** for the common use cases. Below

### Language features

| Feature | Status | Notes |
| --------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **JavaScript & TypeScript** | **Supported** | Uses SWC under the hood. Type-checking is not done by Turbopack (run `tsc --watch` or rely on your IDE for type checks). |
| **ECMAScript (ESNext)** | **Supported** | Turbopack supports the latest ECMAScript features, matching SWC’s coverage. |
| **CommonJS** | **Supported** | `require()` syntax is handled out of the box. |
| **ESM** | **Supported** | Static and dynamic `import` are fully supported. |
| **Babel** | Partially Unsupported | Turbopack does not include Babel by default. However, you can [configure `babel-loader` via the Turbopack config](/docs/app/api-reference/config/next-config-js/turbo#configuring-webpack-loaders). |
| Feature | Status | Notes |
| --------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **JavaScript & TypeScript** | **Supported** | Uses SWC under the hood. Type-checking is not done by Turbopack (run `tsc --watch` or rely on your IDE for type checks). |
| **ECMAScript (ESNext)** | **Supported** | Turbopack supports the latest ECMAScript features, matching SWC’s coverage. |
| **CommonJS** | **Supported** | `require()` syntax is handled out of the box. |
| **ESM** | **Supported** | Static and dynamic `import` are fully supported. |
| **Babel** | Partially Unsupported | Turbopack does not include Babel by default. However, you can [configure `babel-loader` via the Turbopack config](/docs/app/api-reference/config/next-config-js/turbopack#configuring-webpack-loaders). |

### Framework and React features

Expand Down Expand Up @@ -77,12 +77,12 @@ Turbopack in Next.js has **zero-configuration** for the common use cases. Below

### Module resolution

| Feature | Status | Notes |
| --------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Path Aliases** | **Supported** | Reads `tsconfig.json`'s `paths` and `baseUrl`, matching Next.js behavior. |
| **Manual Aliases** | **Supported** | [Configure `resolveAlias` in `next.config.js`](/docs/app/api-reference/config/next-config-js/turbo#resolving-aliases) (similar to `webpack.resolve.alias`). |
| **Custom Extensions** | **Supported** | [Configure `resolveExtensions` in `next.config.js`](/docs/app/api-reference/config/next-config-js/turbo#resolving-custom-extensions). |
| **AMD** | Partially Supported | Basic transforms work; advanced AMD usage is limited. |
| Feature | Status | Notes |
| --------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Path Aliases** | **Supported** | Reads `tsconfig.json`'s `paths` and `baseUrl`, matching Next.js behavior. |
| **Manual Aliases** | **Supported** | [Configure `resolveAlias` in `next.config.js`](/docs/app/api-reference/config/next-config-js/turbopack#resolving-aliases) (similar to `webpack.resolve.alias`). |
| **Custom Extensions** | **Supported** | [Configure `resolveExtensions` in `next.config.js`](/docs/app/api-reference/config/next-config-js/turbopack#resolving-custom-extensions). |
| **AMD** | Partially Supported | Basic transforms work; advanced AMD usage is limited. |

### Performance and Fast Refresh

Expand All @@ -102,7 +102,7 @@ Some features are not yet implemented or not planned:
- The `@value` rule (superseded by CSS variables).
- `:import` and `:export` ICSS rules.
- **`webpack()` configuration** in `next.config.js`
Turbopack replaces webpack, so `webpack()` configs are not recognized. Use the [`experimental.turbo` config](/docs/app/api-reference/config/next-config-js/turbo) instead.
Turbopack replaces webpack, so `webpack()` configs are not recognized. Use the [`experimental.turbo` config](/docs/app/api-reference/config/next-config-js/turbopack) instead.
- **AMP**
Not planned for Turbopack support in Next.js.
- **Yarn PnP**
Expand All @@ -118,14 +118,14 @@ Some features are not yet implemented or not planned:
- `experimental.fallbackNodePolyfills`
We plan to implement these in the future.

For a full, detailed breakdown of each feature flag and its status, see the [Turbopack API Reference](/docs/app/api-reference/config/next-config-js/turbo).
For a full, detailed breakdown of each feature flag and its status, see the [Turbopack API Reference](/docs/app/api-reference/config/next-config-js/turbopack).

## Configuration

Turbopack can be configured via `next.config.js` (or `next.config.ts`) under the `experimental.turbo` key. Configuration options include:
Turbopack can be configured via `next.config.js` (or `next.config.ts`) under the `turbopack` key. Configuration options include:

- **`rules`**
Define additional [webpack loaders](/docs/app/api-reference/config/next-config-js/turbo#configuring-webpack-loaders) for file transformations.
Define additional [webpack loaders](/docs/app/api-reference/config/next-config-js/turbopack#configuring-webpack-loaders) for file transformations.
- **`resolveAlias`**
Create manual aliases (like `resolve.alias` in webpack).
- **`resolveExtensions`**
Expand All @@ -139,19 +139,17 @@ Turbopack can be configured via `next.config.js` (or `next.config.ts`) under the

```js filename="next.config.js"
module.exports = {
experimental: {
turbo: {
// Example: adding an alias and custom file extension
resolveAlias: {
underscore: 'lodash',
},
resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.json'],
turbopack: {
// Example: adding an alias and custom file extension
resolveAlias: {
underscore: 'lodash',
},
resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.json'],
},
}
```

For more in-depth configuration examples, see the [Turbopack config documentation](/docs/app/api-reference/config/next-config-js/turbo).
For more in-depth configuration examples, see the [Turbopack config documentation](/docs/app/api-reference/config/next-config-js/turbopack).

## Generating trace files for performance debugging

Expand Down
2 changes: 1 addition & 1 deletion docs/02-pages/03-api-reference/04-config/01-next-config-js/turbo.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: turbo
description: Configure Next.js with Turbopack-specific options
version: experimental
source: app/api-reference/config/next-config-js/turbo
source: app/api-reference/config/next-config-js/turbopack
---

{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
Loading