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. Results persist to disk between runs.
• Lazy Bundling: Turbopack only bundles what is actually requested by the dev server. This lazy approach can reduce initial compile times and memory usage.

Supported platforms

Turbopack requires platform-specific native bindings. The following platforms are currently supported:

On platforms without native bindings (e.g. FreeBSD, OpenBSD), Next.js falls back to WebAssembly (WASM) bindings. WASM bindings support core SWC features like compilation and minification, but do not support Turbopack. On these platforms, use the --webpack flag:

next dev --webpack
next build --webpack

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

Framework and React features

CSS and styling

Assets

Module resolution

Performance and Fast Refresh

Magic Comments

Turbopack supports webpack-compatible magic comments for controlling import behavior. These comments work with dynamic import(), require(), require.resolve(), and new Worker() expressions (not static import statements).

See Lazy Loading for usage examples.

import.meta.env

Turbopack supports built-in environment metadata through import.meta.env:

These values are statically analyzed, so Turbopack can remove unreachable branches:

if (import.meta.env.DEV) {
  console.log('development mode')
}

You can also read the whole object, destructure it, or use static bracket access:

const { MODE, SSR } = import.meta.env
const baseUrl = import.meta.env['BASE_URL']

Good to know: import.meta.env requires Turbopack. Custom VITE_* variables, Vite custom modes, envPrefix, and envDir are not supported. BASE_URL reflects the Next.js basePath configuration and includes a trailing slash to match Vite's format.

import.meta.glob

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.

const modules = import.meta.glob('./dir/*.js')
// {
//   './dir/foo.js': () => import('./dir/foo.js'),
//   './dir/bar.js': () => import('./dir/bar.js'),
// }

Good to know: import.meta.glob requires Turbopack. It is not available when using webpack.

Lazy loading (default)

By default, each value in the result object is a thunk — a function that returns a Promise for the module. This enables lazy loading:

const modules = import.meta.glob('./dir/*.js')

for (const path in modules) {
  const module = await modules[path]()
  console.log(path, module)
}

Eager loading

Pass { eager: true } to import all matching modules up front. Each value is the module object directly instead of a thunk:

const modules = import.meta.glob('./dir/*.js', { eager: true })

for (const path in modules) {
  console.log(path, modules[path].default)
}

Named imports

Use the import option to select a specific named export from each matched module. This works in both lazy and eager modes:

// Lazy: each value is () => Promise<exportValue>
const defaults = import.meta.glob('./dir/*.js', { import: 'default' })

// Eager: each value is the export value directly
const setups = import.meta.glob('./dir/*.js', { import: 'setup', eager: true })

Query strings

Use the query option to append a query string to every import request. This is useful for loading files as raw strings or URLs:

const rawFiles = import.meta.glob('./dir/*.txt', { query: '?raw' })
const urls = import.meta.glob('./dir/*.png', { query: '?url' })

The query option also accepts an object. Keys and values are URL-encoded and joined into a query string:

const modules = import.meta.glob('./*.ts', {
  query: { bar: 'foo', raw: true },
})
// equivalent to: { query: '?bar=foo&raw=true' }

Multiple patterns and negation

Pass an array of glob patterns as the first argument. Prefix a pattern with ! to exclude matching files:

// Combine multiple directories
const modules = import.meta.glob(['./dir/*.js', './other/*.js'])

// Exclude specific files
const withoutTests = import.meta.glob(['./src/**/*.js', '!**/*.test.js'])

TypeScript

TypeScript types for import.meta.glob are included in Next.js. They are available automatically when "moduleResolution": "bundler" (or "node16" / "nodenext") is set in your tsconfig.json, which is the default for new Next.js projects.

The return type differs based on the eager option:

// Lazy (default) — Record<string, () => Promise<unknown>>
const lazy = import.meta.glob('./dir/*.ts')

// Eager — Record<string, unknown>
const eager = import.meta.glob('./dir/*.ts', { eager: true })

Options reference

Note: The as option (deprecated in Vite 5) is not supported. Use query: '?raw' or query: '?url' instead. The legacy import.meta.globEager() API is also not supported — use import.meta.glob('...', { eager: true }) instead.

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.

Filesystem Root

Turbopack uses the root directory to resolve modules. Files outside of the project root are not resolved.

For example, when linking dependencies outside the project root (via npm link, yarn link, pnpm link, etc.), those linked files will not be resolved by default. To resolve these files, you must configure the root option to the parent directory of both the project and the linked dependencies.

You can configure the filesystem root using turbopack.root option in next.config.js.

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: {
      '~*': '*',
    },
  },
}

CSS / Sass / SCSS decimal precision

Turbopack uses Lightning CSS to compile CSS. Lightning CSS 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, a value that evaluates to 25/17 produces:

• Webpack: line-height: 1.4705882353 (10 digits)
• Turbopack: line-height: 1.47059 (5 digits)

This can lead to subtle rendering differences when migrating from webpack to Turbopack, especially for properties like line-height, letter-spacing, or other calculated values where high precision matters.

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.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.
• ignoreIssue Suppress specific Turbopack errors and warnings from the CLI output and error overlay.

Additionally, the following experimental options are available under experimental in next.config.js:

Table notes:

1. Enabled by default. Set the option to false when the build environment does not preserve the .next/cache directory between builds.

For example, to configure an alias and a custom file extension under the turbopack key:

module.exports = {
  turbopack: {
    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 adding the --internal-trace flag to your dev command:

next dev --internal-trace

This will produce a .next-profiles/trace-turbopack.bin 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.

Version Changes