Turbopack

Turbopack is an incremental bundler optimized for JavaScript and TypeScript, written in Rust, and built into Next.js. You can use Turbopack with both the Pages and App Router for a much faster local development experience.

Why Turbopack?

We built Turbopack to push the performance of Next.js, including:

• Unified Graph: Next.js supports multiple output environments (e.g., client and server). Managing multiple compilers and stitching bundles together can be tedious. Turbopack uses a single, unified graph for all environments.
• Bundling vs Native ESM: Some tools skip bundling in development and rely on the browser's native ESM. This works well for small apps but can slow down large apps due to excessive network requests. Turbopack bundles in dev, but in an optimized way to keep large apps fast.
• Incremental Computation: Turbopack parallelizes work across cores and caches results down to the function level. Once a piece of work is done, Turbopack won’t repeat it.
• Lazy Bundling: Turbopack only bundles what is actually requested by the dev server. This lazy approach can reduce initial compile times and memory usage.

Getting started

To enable Turbopack in your Next.js project, add the --turbopack flag to the dev and build scripts in your package.json file:

{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build --turbopack",
    "start": "next start"
  }
}

Currently, Turbopack for dev is stable, while build is in beta. We are actively working on production support as Turbopack moves closer to stability.

Supported features

Turbopack in Next.js has zero-configuration for the common use cases. Below is a summary of what is supported out of the box, plus some references to how you can configure Turbopack further when needed.

Language features

Framework and React features

CSS and styling

Assets

Module resolution

Performance and Fast Refresh

Known gaps with webpack

There are a number of non-trivial behavior differences between webpack and Turbopack that are important to be aware of when migrating an application. Generally, these are less of a concern for new applications.

CSS Module Ordering

Turbopack will follow JS import order to order CSS modules which are not otherwise ordered. For example:

import utilStyles from './utils.module.css'
import buttonStyles from './button.module.css'
export default function BlogPost() {
  return (
    <div className={utilStyles.container}>
      <button className={buttonStyles.primary}>Click me</button>
    </div>
  )
}

In this example, Turbopack will ensure that utils.module.css will appear before button.module.css in the produced CSS chunk, following the import order

Webpack generally does this as well, but there are cases where it will ignore JS inferred ordering, for example if it infers the JS file is side-effect-free.

This can lead to subtle rendering changes when adopting Turbopack, if applications have come to rely on an arbitrary ordering. Generally, the solution is easy, e.g. have button.module.css @import utils.module.css to force the ordering, or identify the conflicting rules and change them to not target the same properties.

Bundle Sizes

Turbopack does not yet have an equivalent to the Inner Graph Optimization in webpack. This optimization is useful to tree shake large modules. For example:

import heavy from 'some-heavy-dependency.js'
 
export function usesHeavy() {
  return heavy.run()
}
 
export const CONSTANT_VALUE = 3

If an application only uses CONSTANT_VALUE Turbopack will detect this and delete the usesHeavy export but not the corresponding import. However, with the optimization.innerGraph = true option enabled, webpack can delete the import too.

We are planning to offer an equivalent to the innerGraph optimization in Turbopack but it is still under development. If you are affected by this gap, consider manually splitting these modules.

Build Caching

Webpack supports disk build caching to speed up builds. We are planning to support an analogous feature in Turbopack but it is not ready yet. On the next@canary release you can experiment with our solution by enabling the experimental.turbopackPersistentCaching flag.

Good to know: For this reason, when comparing webpack and Turbopack performance, make sure to delete the .next folder between builds to see a fair comparison.

Webpack plugins

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

Unsupported and unplanned features

Some features are not yet implemented or not planned:

• Legacy CSS Modules features
  • 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. In webpack this would treat the .css file as a CSS Module, with Turbopack the .css file will always be global. This means that if you want to use composes in a CSS Module, you need to change the .css file to a .module.css file.
  • @import in CSS Modules importing .css as a CSS Module. In webpack this would treat the .css file as a CSS Module, with Turbopack the .css file will always be global. This means that if you want to use @import in a CSS Module, you need to change the .css file to a .module.css file.
• webpack() configuration in next.config.js Turbopack replaces webpack, so webpack() configs are not recognized. Use the turbopack config instead.
• AMP Not planned for Turbopack support in Next.js.
• Yarn PnP Not planned for Turbopack support in Next.js.
• experimental.urlImports Not planned for Turbopack.
• experimental.esmExternals Not planned. Turbopack does not support the legacy esmExternals configuration in Next.js.
• Some Next.js Experimental Flags
  • experimental.nextScriptWorkers
  • experimental.sri.algorithm
  • 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.

Configuration

Turbopack can be configured via next.config.js (or next.config.ts) under the turbopack key. Configuration options include:

• rules Define additional webpack loaders for file transformations.
• resolveAlias Create manual aliases (like resolve.alias in webpack).
• resolveExtensions Change or extend file extensions for module resolution.
• moduleIds Set how module IDs are generated ('named' vs 'deterministic').
• memoryLimit Set a memory limit (in bytes) for Turbopack.

module.exports = {
  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.

Generating trace files for performance debugging

If you encounter performance or memory issues and want to help the Next.js team diagnose them, you can generate a trace file by appending NEXT_TURBOPACK_TRACING=1 to your dev command:

NEXT_TURBOPACK_TRACING=1 next dev --turbopack

This will produce a .next/trace-turbopack file. Include that file when creating a GitHub issue on the Next.js repo to help us investigate.

Summary

Turbopack is a Rust-based, incremental bundler designed to make local development and builds fast—especially for large applications. It is integrated into Next.js, offering zero-config CSS, React, and TypeScript support.

Stay tuned for more updates as we continue to improve Turbopack and add production build support. In the meantime, give it a try with next dev --turbopack and let us know your feedback.

Version Changes