Skip to main content

Turbopack

Turbopack (beta) is an incremental bundler optimized for JavaScript and TypeScript, written in Rust, and built into Next.js.

Usage​

Turbopack can be used in Next.js in both the pages and app directories for faster local development. To enable Turbopack, use the --turbo flag when running the Next.js development server.

{
  "scripts": {
    "dev": "next dev --turbo",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}

Supported features​

Turbopack in Next.js requires zero-configuration for most users and can be extended for more advanced use cases. To learn more about the currently supported features for Turbopack, view the API Reference.

Unsupported features​

Turbopack currently only supports next dev and does not support next build. We are currently working on support for builds as we move closer towards stability.

These features are currently not supported:

  • Turbopack leverages Lightning CSS which doesn't support some low usage CSS Modules features
    • :local and :global as standalone pseudo classes. Only the function variant is supported, for example: :global(a).
    • The @value rule which has been superseded by CSS variables.
    • :import and :export ICSS rules.
  • Invalid CSS comment syntax such as //
    • CSS comments should be written as /* comment */ per the specification.
    • Preprocessors such as Sass do support this alternative syntax for comments.
  • webpack() configuration in next.config.js
    • Turbopack replaces Webpack, this means that webpack configuration is not supported.
    • To configure Turbopack, see the documentation.
    • A subset of Webpack loaders are supported in Turbopack.
  • Babel (.babelrc)
    • Turbopack leverages the SWC compiler for all transpilation and optimizations. This means that Babel is not included by default.
    • If you have a .babelrc file, you might no longer need it because Next.js includes common Babel plugins as SWC transforms that can be enabled. You can read more about this in the compiler documentation.
    • If you still need to use Babel after verifying your particular use case is not covered, you can leverage Turbopack's support for custom webpack loaders to include babel-loader.
  • Creating a root layout automatically in App Router.
    • This behavior is currently not supported since it changes input files, instead, an error will be shown for you manually add a root layout in the desired location.
  • @next/font (legacy font support).
    • @next/font is deprecated in favor of next/font. next/font is fully supported with Turbopack.
  • new Worker('file', import.meta.url).
    • We are planning to implement this in the future.
  • Relay transforms
    • We are planning to implement this in the future.
  • Blocking .css imports in pages/_document.tsx
    • Currently with webpack Next.js blocks importing .css files in pages/_document.tsx
    • We are planning to implement this warning in the future.
  • `experimental.typedRoutes
    • We are planning to implement this in the future.
  • experimental.nextScriptWorkers
    • We are planning to implement this in the future.
  • experimental.sri.algorithm
    • We are planning to implement this in the future.
  • experimental.fallbackNodePolyfills
    • We are planning to implement this in the future.
  • experimental.esmExternals
    • We are currently not planning to support the legacy esmExternals configuration in Next.js with Turbopack.
  • AMP.
    • We are currently not planning to support AMP in Next.js with Turbopack.
  • Yarn PnP
    • We are currently not planning to support Yarn PnP in Next.js with Turbopack.
  • experimental.urlImports
    • We are currently not planning to support experimental.urlImports in Next.js with Turbopack.
  • :import and :export ICSS rules
    • We are currently not planning to support :import and :export ICSS rules in Next.js with Turbopack as Lightning CSS the CSS parser Turbopack uses does not support these rules.

Generating Trace Files​

Trace files allow the Next.js team to investigate and improve performance metrics and memory usage. To generate a trace file, append NEXT_TURBOPACK_TRACING=1 to the next dev --turbo command, this will generate a .next/trace.log file.

When reporting issues related to Turbopack performance and memory usage, please include the trace file in your GitHub issue.