Unverified Commit c54f9876 authored by Will Binns-Smith's avatar Will Binns-Smith Committed by GitHub

Turbopack: update docs for `config.turbopack` (#77853)

Turbopack: update docs for `config.turbopack`
    
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.

---------
Co-authored-by: 's avatarTim Neutkens <tim@timneutkens.nl>
parent f9962ae2
...@@ -114,7 +114,7 @@ Tailwind CSS version 3.4.8 or newer will warn you about settings that might slow ...@@ -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. 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 ### 6. Optimize memory usage
......
...@@ -557,7 +557,7 @@ Next.js automatically sets up TypeScript if you have a `tsconfig.json`. Make sur ...@@ -557,7 +557,7 @@ Next.js automatically sets up TypeScript if you have a `tsconfig.json`. Make sur
## Bundler Compatibility ## 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 ```bash
next dev --turbopack next dev --turbopack
......
--- ---
title: turbo title: turbopack
description: Configure Next.js with Turbopack-specific options 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 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 ```ts filename="next.config.ts" switcher
import type { NextConfig } from 'next' import type { NextConfig } from 'next'
const nextConfig: NextConfig = { const nextConfig: NextConfig = {
experimental: { turbopack: {
turbo: { // ...
// ...
},
}, },
} }
...@@ -25,10 +22,8 @@ export default nextConfig ...@@ -25,10 +22,8 @@ export default nextConfig
```js filename="next.config.js" switcher ```js filename="next.config.js" switcher
/** @type {import('next').NextConfig} */ /** @type {import('next').NextConfig} */
const nextConfig = { const nextConfig = {
experimental: { turbopack: {
turbo: { // ...
// ...
},
}, },
} }
...@@ -47,12 +42,10 @@ The following options are available for the `turbo` configuration: ...@@ -47,12 +42,10 @@ The following options are available for the `turbo` configuration:
| Option | Description | | 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. | | `rules` | List of supported webpack loaders to apply when running with Turbopack. |
| `resolveAlias` | Map aliased imports to modules to load in their place. | | `resolveAlias` | Map aliased imports to modules to load in their place. |
| `resolveExtensions` | List of extensions to resolve when importing files. | | `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 ### Supported loaders
...@@ -68,6 +61,29 @@ The following loaders have been tested to work with Turbopack's webpack loader i ...@@ -68,6 +61,29 @@ The following loaders have been tested to work with Turbopack's webpack loader i
## Examples ## 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 ### 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: If you need loader support beyond what's built in, many webpack loaders already work with Turbopack. There are currently some limitations:
...@@ -82,13 +98,11 @@ Here is an example below using the [`@svgr/webpack`](https://www.npmjs.com/packa ...@@ -82,13 +98,11 @@ Here is an example below using the [`@svgr/webpack`](https://www.npmjs.com/packa
```js filename="next.config.js" ```js filename="next.config.js"
module.exports = { module.exports = {
experimental: { turbopack: {
turbo: { rules: {
rules: { '*.svg': {
'*.svg': { loaders: ['@svgr/webpack'],
loaders: ['@svgr/webpack'], as: '*.js',
as: '*.js',
},
}, },
}, },
}, },
...@@ -105,12 +119,10 @@ To configure resolve aliases, map imported patterns to their new destination in ...@@ -105,12 +119,10 @@ To configure resolve aliases, map imported patterns to their new destination in
```js filename="next.config.js" ```js filename="next.config.js"
module.exports = { module.exports = {
experimental: { turbopack: {
turbo: { resolveAlias: {
resolveAlias: { underscore: 'lodash',
underscore: 'lodash', mocha: { browser: 'mocha/browser-entry.js' },
mocha: { browser: 'mocha/browser-entry.js' },
},
}, },
}, },
} }
...@@ -128,18 +140,8 @@ To configure resolve extensions, use the `resolveExtensions` field in `next.conf ...@@ -128,18 +140,8 @@ To configure resolve extensions, use the `resolveExtensions` field in `next.conf
```js filename="next.config.js" ```js filename="next.config.js"
module.exports = { module.exports = {
experimental: { turbopack: {
turbo: { resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.json'],
resolveExtensions: [
'.mdx',
'.tsx',
'.ts',
'.jsx',
'.js',
'.mjs',
'.json',
],
},
}, },
} }
``` ```
...@@ -148,27 +150,9 @@ This overwrites the original resolve extensions with the provided list. Make sur ...@@ -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). 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 History
| Version | Changes | | Version | Changes |
| -------- | -------------------------------- | | -------- | ----------------------------------------------- |
| `13.0.0` | `experimental.turbo` introduced. | | `15.3.0` | `experimental.turbo` is changed to `turbopack`. |
| `13.0.0` | `experimental.turbo` introduced. |
...@@ -38,13 +38,13 @@ Turbopack in Next.js has **zero-configuration** for the common use cases. Below ...@@ -38,13 +38,13 @@ Turbopack in Next.js has **zero-configuration** for the common use cases. Below
### Language features ### Language features
| Feature | Status | Notes | | 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). | | **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. | | **ECMAScript (ESNext)** | **Supported** | Turbopack supports the latest ECMAScript features, matching SWC’s coverage. |
| **CommonJS** | **Supported** | `require()` syntax is handled out of the box. | | **CommonJS** | **Supported** | `require()` syntax is handled out of the box. |
| **ESM** | **Supported** | Static and dynamic `import` are fully supported. | | **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). | | **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 ### Framework and React features
...@@ -77,12 +77,12 @@ Turbopack in Next.js has **zero-configuration** for the common use cases. Below ...@@ -77,12 +77,12 @@ Turbopack in Next.js has **zero-configuration** for the common use cases. Below
### Module resolution ### Module resolution
| Feature | Status | Notes | | Feature | Status | Notes |
| --------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | --------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Path Aliases** | **Supported** | Reads `tsconfig.json`'s `paths` and `baseUrl`, matching Next.js behavior. | | **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`). | | **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/turbo#resolving-custom-extensions). | | **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. | | **AMD** | Partially Supported | Basic transforms work; advanced AMD usage is limited. |
### Performance and Fast Refresh ### Performance and Fast Refresh
...@@ -102,7 +102,7 @@ Some features are not yet implemented or not planned: ...@@ -102,7 +102,7 @@ Some features are not yet implemented or not planned:
- The `@value` rule (superseded by CSS variables). - The `@value` rule (superseded by CSS variables).
- `:import` and `:export` ICSS rules. - `:import` and `:export` ICSS rules.
- **`webpack()` configuration** in `next.config.js` - **`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** - **AMP**
Not planned for Turbopack support in Next.js. Not planned for Turbopack support in Next.js.
- **Yarn PnP** - **Yarn PnP**
...@@ -118,14 +118,14 @@ Some features are not yet implemented or not planned: ...@@ -118,14 +118,14 @@ Some features are not yet implemented or not planned:
- `experimental.fallbackNodePolyfills` - `experimental.fallbackNodePolyfills`
We plan to implement these in the future. 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 ## 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`** - **`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`** - **`resolveAlias`**
Create manual aliases (like `resolve.alias` in webpack). Create manual aliases (like `resolve.alias` in webpack).
- **`resolveExtensions`** - **`resolveExtensions`**
...@@ -139,19 +139,17 @@ Turbopack can be configured via `next.config.js` (or `next.config.ts`) under the ...@@ -139,19 +139,17 @@ Turbopack can be configured via `next.config.js` (or `next.config.ts`) under the
```js filename="next.config.js" ```js filename="next.config.js"
module.exports = { module.exports = {
experimental: { turbopack: {
turbo: { // Example: adding an alias and custom file extension
// Example: adding an alias and custom file extension resolveAlias: {
resolveAlias: { underscore: 'lodash',
underscore: 'lodash',
},
resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.json'],
}, },
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 ## Generating trace files for performance debugging
......
...@@ -2,7 +2,7 @@ ...@@ -2,7 +2,7 @@
title: turbo title: turbo
description: Configure Next.js with Turbopack-specific options description: Configure Next.js with Turbopack-specific options
version: experimental 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. */} {/* 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. */}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment