║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║

---

title: Turbopack description: Turbopack is an incremental bundler optimized for JavaScript and TypeScript, written in Rust, and built into Next.js.

{/* 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. */}

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

Turbopack is now the default bundler in Next.js. No configuration is needed to use Turbopack:

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

Using Webpack instead

If you need to use Webpack instead of Turbopack, you can opt-in with the --webpack flag:

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

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

| 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 | Supported | Starting in Next.js 16, Turbopack uses Babel automatically if it detects a configuration file. Unlike in webpack, SWC is always used for Next.js's internal transforms and downleveling to older ECMAScript revisions. Next.js with webpack disables SWC if a Babel configuration file is present. Files in node_modules are excluded, unless you manually configure babel-loader. |

Framework and React features

| Feature | Status | Notes | | --------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------- | | JSX / TSX | Supported | SWC handles JSX/TSX compilation. | | Fast Refresh | Supported | No configuration needed. | | React Server Components (RSC) | Supported | For the Next.js App Router. Turbopack ensures correct server/client bundling. | | Root layout creation | Unsupported | Automatic creation of a root layout in App Router is not supported. Turbopack will instruct you to create it manually. |

CSS and styling

| Feature | Status | Notes | | ------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Global CSS | Supported | Import .css files directly in your application. | | CSS Modules | Supported | .module.css files work natively (Lightning CSS). | | CSS Nesting | Supported | Lightning CSS supports modern CSS nesting. | | @import syntax | Supported | Combine multiple CSS files. | | PostCSS | Supported | Automatically processes postcss.config.js in a Node.js worker pool. Useful for Tailwind, Autoprefixer, etc. | | Sass / SCSS | Supported (Next.js) | For Next.js, Sass is supported out of the box. Custom Sass functions (sassOptions.functions) are not supported because Turbopack's Rust-based architecture cannot directly execute JavaScript functions, unlike webpack's Node.js environment. Use webpack if you need this feature. In the future, Turbopack standalone usage will likely require a loader config. | | Less | Planned via plugins | Not yet supported by default. Will likely require a loader config once custom loaders are stable. | | Lightning CSS | In Use | Handles CSS transformations. Some low-usage CSS Modules features (like :local/:global as standalone pseudo-classes) are not yet supported. See below for more details. |

Assets

| Feature | Status | Notes | | --------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------- | | Static Assets (images, fonts) | Supported | Importing import img from './img.png' works out of the box. In Next.js, returns an object for the <Image /> component. | | JSON Imports | Supported | Named or default imports from .json are supported. |

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 (similar to webpack.resolve.alias). | | Custom Extensions | Supported | Configure resolveExtensions in next.config.js. | | AMD | Partially Supported | Basic transforms work; advanced AMD usage is limited. |

Performance and Fast Refresh

| Feature | Status | Notes | | ------------------------ | ------------- | ---------------------------------------------------------------------------------------- | | Fast Refresh | Supported | Updates JavaScript, TypeScript, and CSS without a full refresh. | | Incremental Bundling | Supported | Turbopack lazily builds only what’s requested by the dev server, speeding up large apps. |

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.

Sass node_modules imports

Turbopack supports importing node_modules Sass files out of the box. Webpack supports a legacy tilde ~ syntax for this, which is not supported by Turbopack.

From:

@import '~bootstrap/dist/css/bootstrap.min.css';

To:

@import 'bootstrap/dist/css/bootstrap.min.css';

If you can't update the imports, you can add a turbopack.resolveAlias configuration to map the ~ syntax to the actual path:

module.exports = {
  turbopack: {
    resolveAlias: {
      '~*': '*',
    },
  },
}

Bundle Sizes

From our testing on production applications, we observed that Turbopack generally produces bundles that are similar in size to Webpack. However, the comparison can be difficult since turbopack tends to produce fewer but larger chunks. Our advice is to focus on higher level metrics like Core Web Vitals or your own application level metrics to compare performance across the two bundlers. We are however aware of one gap that can occasionally cause a large regression.

Turbopack does not yet have an equivalent to the Inner Graph Optimization in webpack which is enabled by default. 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 Inner Graph Optimization, webpack can delete the import too which can drop the dependency as well.

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

Build Caching

Webpack supports disk build caching to improve build performance. Turbopack provides a similar opt-in feature, currently in beta. Starting with Next 16, you can enable Turbopack’s filesystem cache by setting the following experimental flags:

• experimental.turbopackFileSystemCacheForDev
• experimental.turbopackFileSystemCacheForBuild

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 or enable the turbopack filesystem cache feature.

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.
• sassOptions.functions Custom Sass functions defined in sassOptions.functions are not supported. This feature allows defining JavaScript functions that can be called from Sass code during compilation. Turbopack's Rust-based architecture cannot directly execute JavaScript functions passed through sassOptions.functions, unlike webpack's Node.js-based sass-loader which runs entirely in JavaScript. If you're using custom Sass functions, you'll need to use webpack instead of Turbopack.
• webpack() configuration in next.config.js Turbopack replaces webpack, so webpack() configs are not recognized. Use the turbopack config instead.
• 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.

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

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

By default the development server outputs to .next/dev. Read more about isolatedDevBuild.

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.

Version Changes

| Version | Changes | | --------- | ------------------------------------------------------------------------------------------------------------------ | | v16.0.0 | Turbopack becomes the default bundler for Next.js. 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 |

║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║