You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/01-app/04-api-reference/08-turbopack.mdx
+145-60
Original file line number
Diff line number
Diff line change
@@ -5,81 +5,166 @@ description: Turbopack is an incremental bundler optimized for JavaScript and Ty
5
5
6
6
{/* 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. */}
7
7
8
-
[Turbopack](https://turbo.build/pack) is an incremental bundler optimized for JavaScript and TypeScript, written in Rust, and built into Next.js. Turbopack can be used in Next.js in both the `pages` and `app` directories for faster local development.
8
+
Turbopack is an **incremental bundler** optimized for JavaScript and TypeScript, written in Rust, and built into **Next.js**. You can use Turbopack with both the Pages and App Router for a **much faster** local development experience.
9
9
10
-
To enable Turbopack, use the `--turbopack` flag when running the Next.js development server.
10
+
## Why Turbopack?
11
+
12
+
We built Turbopack to push the performance of Next.js, including:
13
+
14
+
-**Unified Graph:** Next.js supports multiple output environments (e.g., client and server). Managing multiple compilers and stitching bundles together can be tedious. Turbopack uses a **single, unified graph** for all environments.
15
+
-**Bundling vs Native ESM:** Some tools skip bundling in development and rely on the browser's native ESM. This works well for small apps but can slow down large apps due to excessive network requests. Turbopack **bundles** in dev, but in an optimized way to keep large apps fast.
16
+
-**Incremental Computation:** Turbopack parallelizes work across cores and **caches** results down to the function level. Once a piece of work is done, Turbopack won’t repeat it.
17
+
-**Lazy Bundling:** Turbopack only bundles what is actually requested by the dev server. This lazy approach can reduce initial compile times and memory usage.
18
+
19
+
## Getting started
20
+
21
+
To enable Turbopack in your Next.js project, use the `--turbopack` flag when running the development server:
11
22
12
23
```json filename="package.json" highlight={3}
13
24
{
14
25
"scripts": {
15
26
"dev": "next dev --turbopack",
16
27
"build": "next build",
17
-
"start": "next start",
18
-
"lint": "next lint"
28
+
"start": "next start"
19
29
}
20
30
}
21
31
```
22
32
23
-
## Reference
33
+
Currently, Turbopack only supports `next dev`. Build (`next build`) is **not yet** supported. We are actively working on production support as Turbopack moves closer to stability.
34
+
35
+
## Supported features
36
+
37
+
Turbopack in Next.js has **zero-configuration** for the common use cases. Below is a summary of what is supported out of the box, plus some references to how you can configure Turbopack further when needed.
|**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). |
|**CommonJS**|**Supported**|`require()` syntax is handled out of the box. |
46
+
|**ESM**|**Supported**| Static and dynamic `import` are fully supported. |
47
+
|**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). |
24
48
25
-
### Supported features
49
+
### Framework and React features
26
50
27
-
Turbopack in Next.js requires zero-configuration for most users and can be extended for more advanced use cases. To learn more about the currently supported features for Turbopack, view the [API Reference](/docs/app/api-reference/config/next-config-js/turbo).
|**Fast Refresh**|**Supported**| No configuration needed. |
55
+
|**React Server Components (RSC)**|**Supported**| For the Next.js App Router. Turbopack ensures correct server/client bundling. |
56
+
|**Root layout creation**| Unsupported | Automatic creation of a root layout in App Router is not supported. Turbopack will instruct you to create it manually. |
28
57
29
-
### Unsupported features
58
+
### CSS and styling
30
59
31
-
Turbopack currently only supports `next dev` and does not support `next build`. We are currently working on support for builds as we move closer towards stability.
|**PostCSS**|**Supported**| Automatically processes `postcss.config.js` in a Node.js worker pool. Useful for Tailwind, Autoprefixer, etc. |
67
+
|**Sass / SCSS**|**Supported** (Next.js) | For Next.js, Sass is supported out of the box. In the future, Turbopack standalone usage will likely require a loader config. |
68
+
|**Less**| Planned via plugins | Not yet supported by default. Will likely require a loader config once custom loaders are stable. |
69
+
|**Lightning CSS**|**In Use**| Handles CSS transformations. Some low-usage CSS Modules features (like `:local/:global` as standalone pseudo-classes) are not yet supported. [See below for more details.](#unsupported-and-unplanned-features)|
32
70
33
-
These features are currently not supported:
71
+
### Assets
34
72
35
-
- Turbopack leverages [Lightning CSS](https://lightningcss.dev/) which doesn't support some low usage CSS Modules features
36
-
-`:local` and `:global` as standalone pseudo classes. Only the function variant is supported, for example: `:global(a)`.
37
-
- The @value rule which has been superseded by CSS variables.
|**Static Assets** (images, fonts) |**Supported**| Importing `import img from './img.png'` works out of the box. In Next.js, returns an object for the `<Image />` component. |
76
+
|**JSON Imports**|**Supported**| Named or default imports from `.json` are supported. |
|**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`). |
84
+
|**Custom Extensions**|**Supported**|[Configure `resolveExtensions` in `next.config.js`](/docs/app/api-reference/config/next-config-js/turbo#resolving-custom-extensions). |
|**Fast Refresh**|**Supported**| Updates JavaScript, TypeScript, and CSS without a full refresh. |
92
+
|**Incremental Bundling**|**Supported**| Turbopack lazily builds only what’s requested by the dev server, speeding up large apps. |
93
+
94
+
## Unsupported and unplanned features
95
+
96
+
Some features are not yet implemented or not planned:
97
+
98
+
-**Production Builds** (`next build`)
99
+
Turbopack currently only supports `next dev`. Support for production builds is in active development.
100
+
-**Legacy CSS Modules features**
101
+
- Standalone `:local` and `:global` pseudo-classes (only the function variant `:global(...)` is supported).
102
+
- The `@value` rule (superseded by CSS variables).
38
103
-`:import` and `:export` ICSS rules.
39
-
-[Invalid CSS comment syntax](https://stackoverflow.com/questions/51843506/are-double-slash-comments-valid-in-css) such as `//`
40
-
- CSS comments should be written as `/* comment */` per the specification.
41
-
- Preprocessors such as Sass do support this alternative syntax for comments.
42
-
-[`webpack()`](/docs/app/api-reference/config/next-config-js/webpack) configuration in `next.config.js`
43
-
- Turbopack replaces Webpack, this means that webpack configuration is not supported.
44
-
- To configure Turbopack, [see the documentation](/docs/app/api-reference/config/next-config-js/turbo).
45
-
- A subset of [Webpack loaders](/docs/app/api-reference/config/next-config-js/turbo#configuring-webpack-loaders) are supported in Turbopack.
46
-
- Babel (`.babelrc`)
47
-
- Turbopack leverages the [SWC](/docs/architecture/nextjs-compiler#why-swc) compiler for all transpilation and optimizations. This means that Babel is not included by default.
48
-
- If you have a `.babelrc` file, you might no longer need it because Next.js includes common Babel plugins as SWC transforms that can be enabled. You can read more about this in the [compiler documentation](/docs/architecture/nextjs-compiler#supported-features).
49
-
- If you still need to use Babel after verifying your particular use case is not covered, you can leverage Turbopack's [support for custom webpack loaders](/docs/app/api-reference/config/next-config-js/turbo#configuring-webpack-loaders) to include `babel-loader`.
50
-
- Creating a root layout automatically in App Router.
51
-
- This behavior is currently not supported since it changes input files, instead, an error will be shown for you to manually add a root layout in the desired location.
52
-
-`@next/font` (legacy font support).
53
-
-`@next/font` is deprecated in favor of `next/font`. [`next/font`](/docs/app/building-your-application/optimizing/fonts) is fully supported with Turbopack.
- We are currently not planning to support `experimental.urlImports` in Next.js with Turbopack.
75
-
-[`:import` and `:export` ICSS rules](https://github.com/css-modules/icss)
76
-
- We are currently not planning to support `:import` and `:export` ICSS rules in Next.js with Turbopack as [Lightning CSS](https://lightningcss.dev/css-modules.html) the CSS parser Turbopack uses does not support these rules.
77
-
-`unstable_allowDynamic` configuration in edge runtime
78
-
79
-
## Examples
80
-
81
-
### Generating Trace Files
82
-
83
-
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-turbopack` file.
84
-
85
-
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.
104
+
-**`webpack()` configuration** in `next.config.js`
105
+
Turbopack replaces webpack, so `webpack()` configs are not recognized. Use the [`experimental.turbo` config](/docs/app/api-reference/config/next-config-js/turbo) instead.
106
+
-**AMP**
107
+
Not planned for Turbopack support in Next.js.
108
+
-**Yarn PnP**
109
+
Not planned for Turbopack support in Next.js.
110
+
-**`experimental.urlImports`**
111
+
Not planned for Turbopack.
112
+
-**`experimental.esmExternals`**
113
+
Not planned. Turbopack does not support the legacy `esmExternals` configuration in Next.js.
114
+
-**Some Next.js Experimental Flags**
115
+
-`experimental.typedRoutes`
116
+
-`experimental.nextScriptWorkers`
117
+
-`experimental.sri.algorithm`
118
+
-`experimental.fallbackNodePolyfills`
119
+
We plan to implement these in the future.
120
+
121
+
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).
122
+
123
+
## Configuration
124
+
125
+
Turbopack can be configured via `next.config.js` (or `next.config.ts`) under the `experimental.turbo` key. Configuration options include:
126
+
127
+
-**`rules`**
128
+
Define additional [webpack loaders](/docs/app/api-reference/config/next-config-js/turbo#configuring-webpack-loaders) for file transformations.
129
+
-**`resolveAlias`**
130
+
Create manual aliases (like `resolve.alias` in webpack).
131
+
-**`resolveExtensions`**
132
+
Change or extend file extensions for module resolution.
133
+
-**`moduleIdStrategy`**
134
+
Set how module IDs are generated (`'named'` vs `'deterministic'`).
135
+
-**`treeShaking`**
136
+
Enable or disable tree shaking in dev and future production builds.
137
+
-**`memoryLimit`**
138
+
Set a memory limit (in bytes) for Turbopack.
139
+
140
+
```js filename="next.config.js"
141
+
module.exports= {
142
+
experimental: {
143
+
turbo: {
144
+
// Example: adding an alias and custom file extension
For more in-depth configuration examples, see the [Turbopack config documentation](/docs/app/api-reference/config/next-config-js/turbo).
155
+
156
+
## Generating trace files for performance debugging
157
+
158
+
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:
159
+
160
+
```bash
161
+
NEXT_TURBOPACK_TRACING=1 next dev --turbopack
162
+
```
163
+
164
+
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.
165
+
166
+
## Summary
167
+
168
+
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.
169
+
170
+
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.
0 commit comments