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 74% 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..4d98fadc9ffc4 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: { + // ... }, } @@ -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 @@ -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: @@ -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', }, }, }, @@ -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' }, }, }, } @@ -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'], }, } ``` @@ -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. | 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. */}