turbopack bundler

58 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

experimental.turbo renamed to turbopack

The turbopack option was previously named experimental.turbo in Next.js versions 13.0.0 to 15.2.x. The experimental.turbo option will be removed in Next.js 16. To migrate, run: npx @next/codemod@latest next-experimental-turbo-to-turbopack .

Turbopack built-in CSS and JavaScript support

Turbopack for Next.js has built-in support for CSS and compiling modern JavaScript, so loaders are not required for these. There is no need for css-loader, postcss-loader, or babel-loader if using @babel/preset-env.

turbopack configuration options reference

Available turbopack options: root (absolute path to application root directory), rules (list of supported webpack loaders to apply with Turbopack), resolveAlias (map aliased imports to modules), resolveExtensions (list of extensions to resolve when importing files), debugIds (enable generation of debug IDs in JavaScript bundles and source maps).

Turbopack supported loaders

The following loaders have been tested to work with Turbopack: babel-loader (configured automatically if a Babel configuration file is found), @svgr/webpack, svg-inline-loader, yaml-loader, string-replace-loader, raw-loader, sass-loader (configured automatically), graphql-tag/loader.

Turbopack webpack loader features not supported

The following webpack loader API features are not supported in Turbopack: importModule, loadModule, emitFile, fs (except fs.readFile which is partially supported), version, mode, target, utils, and resolve (use getResolve instead).

Turbopack root directory detection

Next.js automatically detects the project root directory by looking for one of these files: pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lock, or bun.lockb. You can manually set the root option in turbopack config if needed.

Turbopack rules glob pattern matching

Globs in the turbopack.rules object match based on file name unless the glob contains a / character, which causes it to match based on the full project-relative file path. Windows file paths are normalized to use unix-style / path separators. Turbopack uses a modified version of the Rust globset library.

Turbopack loaders configuration restrictions

Only a core subset of the webpack loader API is implemented in Turbopack. Only loaders that return JavaScript code are supported; loaders that transform stylesheets or images are not supported. Options passed to webpack loaders must be plain JavaScript primitives, objects, and arrays - it is not possible to pass require() plugin modules as option values.

Turbopack rules array syntax for disjoint conditions

Turbopack rules can be specified as an array of objects to model disjoint conditions. When an array is provided, all matching rules are executed in order.

Turbopack rule condition operators

Turbopack rule conditions support boolean operators: {all: [...]}, {any: [...]}, {not: ...}. Customizable operators include {path: string | RegExp}, {content: RegExp}, {query: string | RegExp}, {contentType: string | RegExp}. Built-in conditions: browser, foreign, development, production, node, edge-light.

Turbopack available module types

Turbopack supports the following module types: asset (emit file and return URL), ecmascript (process as JavaScript), typescript (process as TypeScript), css (process as CSS), css-module (process as CSS module), json (parse as JSON and export), wasm (process as WebAssembly), node (process as native Node.js addon), raw (export contents as string, alias of text), text (export contents as string), bytes (export contents as Uint8Array).

Turbopack module type with loaders

The type option in Turbopack rules can be combined with loaders. When both are specified, loaders run first, then the result is processed according to the specified type.

Turbopack inline loader configuration with import attributes

Loaders can be applied to individual imports using the with clause (import attributes). Supported attributes: turbopackLoader (loader name), turbopackLoaderOptions (JSON string of loader options), turbopackAs (rename pattern for output), turbopackModuleType (set module type for output). Example: import rawText from '../data.txt' with { turbopackLoader: 'raw-loader', turbopackAs: '*.js' }

Turbopack inline loader with options example

Loaders with options can be applied via import attributes using a JSON-encoded string: import value from '../data.js' with { turbopackLoader: 'string-replace-loader', turbopackLoaderOptions: '{"search":"PLACEHOLDER","replace":"replaced value"}' }

Turbopack import attributes are not webpack compatible

Import attributes with turbopackLoader are Turbopack-specific and are not supported by webpack. This feature requires the with keyword (not assert) in import statements.

Turbopack resolveAlias configuration

Turbopack supports module resolution through aliases similar to webpack's resolve.alias. For example: resolveAlias: { underscore: 'lodash', mocha: { browser: 'mocha/browser-entry.js' } } will alias underscore imports to lodash and conditionally alias mocha imports to the browser entry point.

Turbopack resolveAlias conditional exports

Turbopack supports conditional aliasing similar to Node.js conditional exports. Currently only the browser condition is supported for conditional aliasing.

Turbopack resolveExtensions configuration

Turbopack supports custom extension resolution via resolveExtensions field. This overwrites the original resolve extensions with the provided list, so default extensions must be included explicitly. Example: resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.json']

Turbopack debugIds configuration

Turbopack can be configured to generate debug IDs in JavaScript bundles and source maps by setting debugIds: true in turbopack config. The option automatically adds a polyfill for debug IDs to ensure compatibility, and debug IDs are available in the globalThis._debugIds global variable.

Turbopack rules with loaders configuration example

Example configuration for @svgr/webpack loader to import .svg files as React components: module.exports = { turbopack: { rules: { '*.svg': { loaders: ['@svgr/webpack'], as: '*.js', }, }, }, }

Turbopack loader with options configuration example

Example configuration for loader with options: module.exports = { turbopack: { rules: { '*.svg': { loaders: [{ loader: '@svgr/webpack', options: { icon: true }, }], as: '*.js', }, }, }, }

Turbopack advanced rule conditions example

Example of advanced rule conditions: module.exports = { turbopack: { rules: { '*': { condition: { all: [{ not: 'foreign' }, { path: /^img\/[0-9]{3}\// }, { any: [{ path: '*.svg' }, { query: /[?&]svgr(?=&|$)/ }, { content: /\<svg\W/ }] }] }, loaders: ['@svgr/webpack'], as: '*.js', }, }, }, }

Turbopack asset module type example

Example of using asset module type: module.exports = { turbopack: { rules: { '*.svg': { type: 'asset', }, }, }, }. When using type: 'asset', importing the file returns its URL: import svgUrl from './icon.svg'; export default function Page() { return <img src={svgUrl} alt="Icon" /> }

Turbopack root directory configuration example

Example of manually configuring the root directory: module.exports = { turbopack: { root: path.join(__dirname, '..'), }, }. To resolve files from linked dependencies (via npm link, yarn link, pnpm link), set turbopack.root to the parent directory of both the project and the linked dependencies.

Turbopack resolveAlias example

Example of resolveAlias configuration: module.exports = { turbopack: { resolveAlias: { underscore: 'lodash', mocha: { browser: 'mocha/browser-entry.js' }, }, }, }

Turbopack resolveExtensions example

Example of resolveExtensions configuration: module.exports = { turbopack: { resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.json'], }, }

Turbopack debugIds configuration example

Example of debugIds configuration: module.exports = { turbopack: { debugIds: true, }, }

Turbopack version history

Version history: 16.2.0 added turbopackLoader import attributes, turbopack.rules.*.type, turbopack.rules.*.condition.contentType, turbopack.rules.*.condition.query. 16.0.0 added turbopack.debugIds and turbopack.rules.*.condition. 15.3.0 changed experimental.turbo to turbopack. 13.0.0 introduced experimental.turbo.

Turbopack path condition matching behavior

In Turbopack rule conditions, the path operator can be a RegExp or glob string. A RegExp matches anywhere in the full project-relative file path, while a glob string is treated as a glob pattern.

Turbopack content condition matching

In Turbopack rule conditions, the content operator is always a RegExp and can match anywhere in the file content.

Turbopack query condition matching

In Turbopack rule conditions, the query operator matches the import's query string (e.g., ?foo in import './file?foo'). A string must match exactly, while a RegExp can match the query string partially.

Turbopack contentType condition matching

In Turbopack rule conditions, the contentType operator matches the MIME content type of the resource (e.g., from data URLs like data:text/plain,...). A string is treated as a glob pattern (e.g., text/*, image/*), while a RegExp can match the content type partially.

IS_WEBPACK_TEST environment variable forces webpack bundler

Set IS_WEBPACK_TEST=1 to force webpack bundler when reproducing CI failures. Turbopack is the default bundler in Next.js.

Turbopack is the default bundler in Next.js

Turbopack is the default bundler in Next.js as of version 16.0.0. No configuration is needed to use it. It is an incremental bundler optimized for JavaScript and TypeScript, written in Rust, and built into Next.js.

Turbopack supported platforms and architectures

Turbopack requires platform-specific native bindings. Supported platforms are: macOS (Darwin) with x64 and ARM64, Windows with x64 and ARM64, Linux (glibc) with x64 and ARM64, and Linux (musl) with x64 and ARM64. On platforms without native bindings like FreeBSD or OpenBSD, Next.js falls back to WebAssembly (WASM) bindings, which support core SWC features like compilation and minification but do not support Turbopack.

Switch to Webpack using --webpack flag

To use Webpack instead of Turbopack, use the `--webpack` flag with next dev and next build commands. For example: `next dev --webpack` and `next build --webpack`.

Turbopack language features supported

Turbopack supports: JavaScript and TypeScript (uses SWC under the hood; type-checking is not done by Turbopack), ECMAScript (ESNext) matching SWC's coverage, CommonJS via require() syntax, ESM via static and dynamic import, and Babel (starting in Next.js 16, Turbopack uses Babel automatically if a configuration file is detected, but SWC is always used for Next.js's internal transforms and downleveling).

Turbopack framework and React features

Turbopack supports: JSX/TSX compilation via SWC, Fast Refresh with no configuration needed, React Server Components (RSC) for the Next.js App Router with correct server/client bundling. Root layout creation is unsupported; Turbopack will instruct you to create it manually.

Turbopack CSS and styling features

Turbopack supports: Global CSS (import .css files directly), CSS Modules (.module.css files work natively via Lightning CSS), CSS Nesting (Lightning CSS supports modern CSS nesting), @import syntax for combining CSS files, and PostCSS (automatically processes postcss.config.js, .mjs, .cjs, .ts, .mts, .cts in a Node.js worker pool). Sass/SCSS is supported out of the box for Next.js, but custom Sass functions (sassOptions.functions) are not supported due to Turbopack's Rust-based architecture. Less is planned via plugins but not yet supported by default.

Turbopack asset handling

Turbopack supports importing static assets like images and fonts (import img from './img.png' works out of the box, and in Next.js returns an object for the Image component), and JSON imports (named or default imports from .json files).

Turbopack module resolution features

Turbopack supports: Path Aliases (reads tsconfig.json's paths and baseUrl matching Next.js behavior), Manual Aliases (configure resolveAlias in next.config.js similar to webpack.resolve.alias), Custom Extensions (configure resolveExtensions in next.config.js), and partially supports AMD (basic transforms work but advanced AMD usage is limited).

Turbopack magic comments for import control

Turbopack supports webpack-compatible magic comments for controlling import behavior with dynamic import(), require(), require.resolve(), and new Worker() expressions: webpackIgnore: true (skip bundling, preserve import, supported in both Webpack and Turbopack), turbopackIgnore: true (skip bundling, Turbopack-only), turbopackOptional: true (suppress resolve errors, Turbopack-only), and webpackOptional: true (not supported).

Turbopack configuration example

Example configuration in next.config.js: module.exports = { turbopack: { resolveAlias: { underscore: 'lodash' }, resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.json'] } }

Turbopack import.meta.env properties

Turbopack supports import.meta.env with the following properties: DEV (boolean, true when MODE is not 'production'), PROD (boolean, true when MODE is 'production'), MODE (string, the compile-time NODE_ENV defaulting to 'development'), BASE_URL (string, the Next.js basePath with a trailing slash, '/' by default), and SSR (boolean, true in server bundles and false in browser and client bundles). These values are statically analyzed and Turbopack can remove unreachable branches.

Turbopack import.meta.glob API

Turbopack supports import.meta.glob(), a Vite-compatible API for importing multiple modules at once using glob patterns. The result is an object keyed by the file path relative to the calling file. By default, each value is a thunk that returns a Promise for lazy loading. Pass { eager: true } to import all matching modules synchronously. Use the import option to select a specific named export, the query option to append a query string to every import request, pass an array of glob patterns for multiple patterns and use ! prefix to exclude files, and caseSensitive (default true) to control case sensitivity.

Turbopack import.meta.glob options reference

import.meta.glob options: eager (boolean, default false, import modules synchronously instead of returning thunks), import (string, default undefined, named export to select from each matched module), query (string or Record<string, string | boolean>, default undefined, query string or object to append to each import), base (string, default undefined, override the base path used for resolving patterns and keying results), caseSensitive (boolean, default true, match glob patterns case-sensitively or set to false to ignore ASCII case).

Turbopack filesystem root behavior

Turbopack uses the root directory to resolve modules. Files outside of the project root are not resolved by default. When linking dependencies outside the project root via npm link, yarn link, pnpm link, etc., those files will not be resolved. Configure the filesystem root using turbopack.root option in next.config.js to resolve these files.

Turbopack CSS module ordering

Turbopack follows JavaScript import order to order CSS modules that are not otherwise ordered. Webpack generally does this as well but ignores JS inferred ordering in some cases (e.g., if it infers the JS file is side-effect-free). This can lead to subtle rendering changes when adopting Turbopack. Solutions include having a CSS module import another to force ordering or identify conflicting rules and change them to not target the same properties.

Turbopack Sass node_modules imports without tilde syntax

Turbopack supports importing node_modules Sass files out of the box but does not support the legacy tilde ~ syntax that Webpack supports. Change @import '~bootstrap/dist/css/bootstrap.min.css' to @import 'bootstrap/dist/css/bootstrap.min.css'. If unable to update imports, add turbopack.resolveAlias configuration: { '~*': '*' }.

Turbopack decimal precision differences from Webpack

Turbopack uses Lightning CSS which uses 5 digits of decimal precision for numeric CSS values, while Webpack uses 10 digits. This applies to both plain CSS and Sass/SCSS output. For example, 25/17 produces 1.47059 (5 digits) in Turbopack vs 1.4705882353 (10 digits) in Webpack. This can lead to subtle rendering differences when migrating from Webpack to Turbopack, especially for properties like line-height and letter-spacing.

Turbopack does not support webpack plugins

Turbopack does not support webpack plugins. This affects third-party tools that rely on webpack's plugin system for integration. Turbopack does support webpack loaders. If you depend on webpack plugins, you need to find Turbopack-compatible alternatives or continue using webpack until equivalent functionality is available.

Turbopack unsupported legacy CSS Modules features

Turbopack does not support: standalone :local and :global pseudo-classes (only the function variant :global(...) is supported), the @value rule (superseded by CSS variables), :import and :export ICSS rules, composes in .module.css composing a .css file (change the .css file to .module.css to make this work), and @import in CSS Modules importing .css as a CSS Module (change the .css file to .module.css).

Turbopack unsupported features

Unsupported features in Turbopack: sassOptions.functions (custom Sass functions cannot be executed), webpack() configuration in next.config.js (use turbopack config instead), Yarn PnP (not planned), experimental.urlImports (not planned), experimental.esmExternals (not planned), experimental.nextScriptWorkers (planned for future), and experimental.fallbackNodePolyfills (planned for future).

Turbopack configuration options in next.config.js

Turbopack is configured via next.config.js (or next.config.ts) under the turbopack key with options: rules (define additional webpack loaders for file transformations), resolveAlias (create manual aliases like resolve.alias in webpack), and resolveExtensions (change or extend file extensions for module resolution). Additionally, ignoreIssue configuration is available to suppress specific Turbopack errors and warnings.

Turbopack experimental configuration options table

Experimental options available under experimental in next.config.js: turbopackFileSystemCacheForDev (boolean, default true for dev, enable filesystem cache for dev server), turbopackFileSystemCacheForBuild (boolean, default true for build, enable filesystem cache for builds), turbopackMinify (boolean or {server, client, edge}, default false for dev and true for build, enable minification), turbopackSourceMaps (boolean, default true for dev and productionBrowserSourceMaps for build, enable source maps), turbopackInputSourceMaps (boolean, default true for both, enable extraction of source maps from input files), turbopackModuleFragments (boolean, default false, split modules into fragments and chunks), turbopackRemoveUnusedImports (boolean, default false for dev and true for build, enable removing unused imports), turbopackRemoveUnusedExports (boolean, default false for dev and true for build, enable removing unused exports), turbopackInferModuleSideEffects (boolean, default true, enable local analysis for tree shaking), turbopackScopeHoisting (boolean, default false for dev and true for build, always disabled in dev mode), turbopackClientSideNestedAsyncChunking (boolean, default false for dev and true for build, enable nested async chunking for client-side), turbopackServerSideNestedAsyncChunking (boolean, default false for both, enable nested async chunking for server-side), turbopackImportTypeBytes (boolean, default false, enable support for with {type: 'bytes'} for ESM imports), turbopackUseBuiltinBabel (boolean, default true, enable automatic Babel loader when config file present), turbopackUseBuiltinSass (boolean, default true, enable automatic Sass loader), turbopackModuleIds (string 'named' or 'deterministic', default 'named' for dev and 'deterministic' for build, module ID strategy), turbopackLocalPostcssConfig (boolean, default false, resolve postcss.config.js from CSS file's directory first), and turbopackWorkerAssetPrefix (string, default undefined, custom asset prefix for Web Worker URLs).

Generate trace files for Turbopack performance debugging

To generate a trace file for performance or memory issue debugging, add the --internal-trace flag to the dev command: next dev --internal-trace. This produces a .next-profiles/trace-turbopack.bin file that can be included when creating a GitHub issue on the Next.js repo.

Turbopack version changes

Version changes: v16.0.0 - Turbopack becomes the default bundler for Next.js with automatic support for Babel when a configuration file is found. v15.5.0 - Turbopack support for build beta. v15.3.0 - Experimental support for build. v15.0.0 - Turbopack for dev stable.

Next.js default bundler features and support

Turbopack is the default bundler in Next.js providing zero-configuration for common use cases. It features a unified graph for all environments, bundles in development in an optimized way for large apps, performs incremental computation with caching down to the function level and filesystem persistence, and uses lazy bundling to only bundle what is requested by the dev server.

Give your agent this brain