Skip to main content
Turbopack is an incremental, Rust-based bundler built into Next.js. It is the default bundler starting in Next.js 16 and is used for both next dev and next build.
To use Webpack instead of Turbopack, pass the --webpack flag to next dev or next build.

​
Supported platforms

PlatformArchitectures
macOSx64, ARM64
Windowsx64, ARM64
Linux (glibc)x64, ARM64
Linux (musl)x64, ARM64
On platforms without native bindings (e.g. FreeBSD), Next.js falls back to WebAssembly bindings. WASM does not support Turbopack—use the --webpack flag on those platforms.

​
Enabling Turbopack

Turbopack is enabled by default. No configuration is needed:
package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build"
  }
}
To force Webpack:
package.json
{
  "scripts": {
    "dev": "next dev --webpack",
    "build": "next build --webpack"
  }
}

​
Configuration

Turbopack is configured under the turbopack key in next.config.js:
next.config.js
module.exports = {
  turbopack: {
    resolveAlias: {
      underscore: 'lodash',
    },
    resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.json'],
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}

​
Resolve aliases

Map module names to different packages, similar to resolve.alias in webpack:
​
turbopack.resolveAlias
object
A map of module name strings to their replacement module paths.
next.config.js
module.exports = {
  turbopack: {
    resolveAlias: {
      // Replace 'underscore' with 'lodash'
      underscore: 'lodash',
      // Map to different packages per environment
      mocha: { browser: 'mocha/browser-entry.js' },
      // Map Sass tilde imports to node_modules
      '~*': '*',
    },
  },
}

​
Resolve extensions

Change or extend the file extensions Turbopack resolves:
​
turbopack.resolveExtensions
string[]
Ordered list of file extensions to try when resolving imports without an extension.
next.config.js
module.exports = {
  turbopack: {
    resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.json'],
  },
}

​
Webpack loaders

Turbopack supports a subset of webpack loader semantics for transforming files:
​
turbopack.rules
object
A map of glob patterns to loader configurations.
next.config.js
module.exports = {
  turbopack: {
    rules: {
      // Transform .svg files with @svgr/webpack
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
      // Transform .mdx with options
      '*.mdx': {
        loaders: [
          {
            loader: '@mdx-js/loader',
            options: {
              providerImportSource: '@mdx-js/react',
            },
          },
        ],
        as: '*.js',
      },
    },
  },
}
Each rule value accepts:
​
turbopack.rules[glob].loaders
string[] | object[]
Loader paths or { loader, options } objects to apply in order.
​
turbopack.rules[glob].as
string
Rename the output file extension (e.g. '*.js' to treat loader output as JavaScript).

​
Root directory

​
turbopack.root
string
The filesystem root used for module resolution. Defaults to the project directory. Set this when using symlinked packages outside the project root (e.g. npm link).
next.config.js
const path = require('path')

module.exports = {
  turbopack: {
    root: path.join(__dirname, '..'),
  },
}

​
Experimental options

The following options are available under experimental in next.config.js:
OptionDescriptionDefault (dev)Default (build)
turbopackFileSystemCacheForDevEnable filesystem cache for the dev servertrueN/A
turbopackFileSystemCacheForBuildEnable filesystem cache for buildsN/Afalse
turbopackMinifyEnable minificationfalsetrue
turbopackSourceMapsEnable source mapstrueproductionBrowserSourceMaps
turbopackInputSourceMapsExtract source maps from input filestruetrue
turbopackTreeShakingUse advanced module-fragments tree shakingfalsefalse
turbopackRemoveUnusedImportsRemove unused imports (requires turbopackRemoveUnusedExports)falsetrue
turbopackRemoveUnusedExportsRemove unused exportsfalsetrue
turbopackModuleIdsModule ID strategy: 'named' or 'deterministic''named''deterministic'
turbopackScopeHoistingEnable scope hoisting (always off in dev)falsetrue
next.config.js
module.exports = {
  experimental: {
    turbopackFileSystemCacheForBuild: true,
    turbopackModuleIds: 'deterministic',
  },
}

​
Known differences from webpack

​
Filesystem root

Turbopack resolves modules relative to the project root. Files and symlinks outside the root are not resolved by default. Use turbopack.root to extend the resolution boundary.

​
CSS module ordering

Turbopack orders CSS modules according to JavaScript import order. Webpack sometimes ignores this order for side-effect-free modules, which can cause subtle differences. To enforce CSS order, use @import in CSS modules:
button.module.css
@import './utils.module.css';

​
Sass ~ imports

Webpack supports tilde (~) prefixes for Sass node_modules imports. Turbopack does not. Replace: 
/* Before */
@import '~bootstrap/dist/css/bootstrap.min.css';

/* After */
@import 'bootstrap/dist/css/bootstrap.min.css';
Or configure an alias:
next.config.js
module.exports = {
  turbopack: {
    resolveAlias: { '~*': '*' },
  },
}

​
Webpack plugins

Turbopack does not support webpack plugins. Webpack loaders are supported via the turbopack.rules configuration.

​
Performance tracing

To generate a trace file for performance debugging: 
NEXT_TURBOPACK_TRACING=1 next dev
This creates a .next/dev/trace-turbopack file. Include it when reporting issues on the Next.js GitHub repository.

​
Version history

VersionChanges
v16.0.0Turbopack becomes the default bundler; automatic Babel support
v15.5.0Turbopack build support in beta
v15.3.0Experimental build support
v15.0.0Turbopack dev stable

Build docs developers (and LLMs) love

Get started for freeTalk to us