From 01ede8ae309e6029486c381ec7b63d01a902ec72 Mon Sep 17 00:00:00 2001 From: Will Binns-Smith Date: Fri, 4 Apr 2025 17:31:18 -0700 Subject: [PATCH 1/3] Turbopack: update docs for `config.turbopack` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As `turbo.mdx` is renamed to `turbopack.mdx`, we’ll need a redirect on the nextjs.org website to take users to the new location. This will be a separate PR in its repository. --- .../06-optimizing/14-local-development.mdx | 2 +- .../11-upgrading/06-from-create-react-app.mdx | 2 +- .../{turbo.mdx => turbopack.mdx} | 75 ++++++++----------- docs/01-app/05-api-reference/08-turbopack.mdx | 48 ++++++------ .../04-config/01-next-config-js/turbo.mdx | 2 +- 5 files changed, 59 insertions(+), 70 deletions(-) rename docs/01-app/05-api-reference/05-config/01-next-config-js/{turbo.mdx => turbopack.mdx} (78%) diff --git a/docs/01-app/03-building-your-application/06-optimizing/14-local-development.mdx b/docs/01-app/03-building-your-application/06-optimizing/14-local-development.mdx index 545e86581dae9..074dbbc38fec4 100644 --- a/docs/01-app/03-building-your-application/06-optimizing/14-local-development.mdx +++ b/docs/01-app/03-building-your-application/06-optimizing/14-local-development.mdx @@ -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 diff --git a/docs/01-app/03-building-your-application/11-upgrading/06-from-create-react-app.mdx b/docs/01-app/03-building-your-application/11-upgrading/06-from-create-react-app.mdx index 73db3aede0c88..b6e22017595ea 100644 --- a/docs/01-app/03-building-your-application/11-upgrading/06-from-create-react-app.mdx +++ b/docs/01-app/03-building-your-application/11-upgrading/06-from-create-react-app.mdx @@ -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 diff --git a/docs/01-app/05-api-reference/05-config/01-next-config-js/turbo.mdx b/docs/01-app/05-api-reference/05-config/01-next-config-js/turbopack.mdx similarity index 78% rename from docs/01-app/05-api-reference/05-config/01-next-config-js/turbo.mdx rename to docs/01-app/05-api-reference/05-config/01-next-config-js/turbopack.mdx index a5bc7801825ff..1f150eadb7b7d 100644 --- a/docs/01-app/05-api-reference/05-config/01-next-config-js/turbo.mdx +++ b/docs/01-app/05-api-reference/05-config/01-next-config-js/turbopack.mdx @@ -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 `Content` 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: { + // ... }, } @@ -25,10 +22,8 @@ export default nextConfig ```js filename="next.config.js" switcher /** @type {import('next').NextConfig} */ const nextConfig = { - experimental: { - turbo: { - // ... - }, + turbopack: { + // ... }, } @@ -51,8 +46,6 @@ The following options are available for the `turbo` configuration: | `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 @@ -66,6 +59,17 @@ The following loaders have been tested to work with Turbopack's webpack loader i - [`raw-loader`](https://www.npmjs.com/package/raw-loader) - [`sass-loader`](https://www.npmjs.com/package/sass-loader) +### Experimental options + +Experimental options for Turbopack are available under the top-level `experimental` key in `next.config.js`: + +| Option | Description | +| ---------------------- | ------------------------------------------------------------------------- | +| `turbopackTreeShaking` | Enable tree shaking for the turbopack dev server and build. | +| `turbopackMemoryLimit` | A target memory limit for turbo, in bytes. | +| `turbopackSourceMaps` | Write sourcemaps (defaults to true) | +| `turbopackMinify` | Minify output code (fefaults to true in build mode and false in dev mode) | + ## Examples ### Configuring webpack loaders @@ -82,13 +86,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', }, }, }, @@ -105,12 +107,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' }, }, }, } @@ -128,18 +128,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'], }, } ``` @@ -161,7 +151,7 @@ To configure the module IDs strategy, use the `moduleIds` field in `next.config. ```js filename="next.config.js" module.exports = { - turbo: { + turbopack: { moduleIds: 'deterministic', }, } @@ -169,6 +159,7 @@ module.exports = { ## 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. | diff --git a/docs/01-app/05-api-reference/08-turbopack.mdx b/docs/01-app/05-api-reference/08-turbopack.mdx index 9f26346e65b21..ac072f7702fc2 100644 --- a/docs/01-app/05-api-reference/08-turbopack.mdx +++ b/docs/01-app/05-api-reference/08-turbopack.mdx @@ -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 @@ -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 @@ -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** @@ -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`** @@ -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 diff --git a/docs/02-pages/03-api-reference/04-config/01-next-config-js/turbo.mdx b/docs/02-pages/03-api-reference/04-config/01-next-config-js/turbo.mdx index 1be780969309f..6b55ded59ee31 100644 --- a/docs/02-pages/03-api-reference/04-config/01-next-config-js/turbo.mdx +++ b/docs/02-pages/03-api-reference/04-config/01-next-config-js/turbo.mdx @@ -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 `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} From 460bbd355f79454f2a76026c549154acf4636114 Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Wed, 9 Apr 2025 13:18:34 +0200 Subject: [PATCH 2/3] Document `root` option --- .../05-config/01-next-config-js/turbopack.mdx | 31 +++++++++++++------ 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/docs/01-app/05-api-reference/05-config/01-next-config-js/turbopack.mdx b/docs/01-app/05-api-reference/05-config/01-next-config-js/turbopack.mdx index 1f150eadb7b7d..81249d29eed96 100644 --- a/docs/01-app/05-api-reference/05-config/01-next-config-js/turbopack.mdx +++ b/docs/01-app/05-api-reference/05-config/01-next-config-js/turbopack.mdx @@ -42,6 +42,7 @@ 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. | @@ -59,18 +60,30 @@ The following loaders have been tested to work with Turbopack's webpack loader i - [`raw-loader`](https://www.npmjs.com/package/raw-loader) - [`sass-loader`](https://www.npmjs.com/package/sass-loader) -### Experimental options +## Examples -Experimental options for Turbopack are available under the top-level `experimental` key in `next.config.js`: +### Root directory -| Option | Description | -| ---------------------- | ------------------------------------------------------------------------- | -| `turbopackTreeShaking` | Enable tree shaking for the turbopack dev server and build. | -| `turbopackMemoryLimit` | A target memory limit for turbo, in bytes. | -| `turbopackSourceMaps` | Write sourcemaps (defaults to true) | -| `turbopackMinify` | Minify output code (fefaults to true in build mode and false in dev mode) | +Turbopack uses the root directory to resolve modules. Files outside of the project root are not resolved. -## Examples +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 From 4fcfdccb33890185c74e5be7c552396e9169d589 Mon Sep 17 00:00:00 2001 From: Tim Neutkens Date: Wed, 9 Apr 2025 13:27:31 +0200 Subject: [PATCH 3/3] Remove moduleIds docs --- .../05-config/01-next-config-js/turbopack.mdx | 20 ------------------- 1 file changed, 20 deletions(-) diff --git a/docs/01-app/05-api-reference/05-config/01-next-config-js/turbopack.mdx b/docs/01-app/05-api-reference/05-config/01-next-config-js/turbopack.mdx index 81249d29eed96..4d98fadc9ffc4 100644 --- a/docs/01-app/05-api-reference/05-config/01-next-config-js/turbopack.mdx +++ b/docs/01-app/05-api-reference/05-config/01-next-config-js/turbopack.mdx @@ -46,7 +46,6 @@ The following options are available for the `turbo` configuration: | `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 | ### Supported loaders @@ -151,25 +150,6 @@ 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 = { - turbopack: { - moduleIds: 'deterministic', - }, -} -``` - ## Version History | Version | Changes |