Turbopack

You are an expert in Turbopack — the Rust-powered JavaScript/TypeScript bundler built by Vercel. It is the default bundler in Next.js 16.

Key Features

• Instant HMR: Hot Module Replacement that doesn't degrade with app size
• File System Caching: Compiler artifacts cached on disk between runs — up to 14x faster startup on large projects. turbopackFileSystemCacheForDev defaults to true since Next.js 16.1, and turbopackFileSystemCacheForBuild defaults to true since Next.js 16.3 — no config needed for either.
• Multi-environment builds: Browser, Server, Edge, SSR, React Server Components
• Native RSC support: Built for React Server Components from the ground up
• TypeScript, JSX, CSS, CSS Modules, WebAssembly: Out of the box
• Rust-powered: Incremental computation engine for maximum performance

Configuration (Next.js 16)

In Next.js 16, Turbopack config is top-level (moved from experimental.turbo):

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    // Resolve aliases (like webpack resolve.alias)
    resolveAlias: {
      'old-package': 'new-package',
    },
    // Custom file extensions to resolve
    resolveExtensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],
  },
}

export default nextConfig

CSS and CSS Modules Handling

Turbopack handles CSS natively without additional configuration.

Global CSS

Import global CSS in your root layout:

// app/layout.tsx
import './globals.css'

CSS Modules

CSS Modules work out of the box with .module.css files:

// components/Button.tsx
import styles from './Button.module.css'

export function Button({ children }) {
  return <button className={styles.primary}>{children}</button>
}

PostCSS

Turbopack reads your postcss.config.js automatically. Tailwind CSS v4 works with zero config:

// postcss.config.js
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
    autoprefixer: {},
  },
}

Sass / SCSS

Install sass and import .scss files directly — Turbopack compiles them natively:

npm install sass

import styles from './Component.module.scss'

Common CSS pitfalls

• CSS ordering differs from webpack: Turbopack may load CSS chunks in a different order. Avoid relying on source-order specificity across files — use more specific selectors or CSS Modules.
• @import in global CSS: Use standard CSS @import — Turbopack resolves them, but circular imports cause build failures.
• CSS-in-JS libraries: styled-components and emotion work but require their SWC plugins configured under compiler in next.config.

Tree Shaking

Turbopack performs tree shaking at the module level in production builds. Key behaviors:

• ES module exports: Only used exports are included — write export on each function/constant rather than barrel export *
• Side-effect-free packages: Mark packages as side-effect-free in package.json to enable aggressive tree shaking:

{
  "name": "my-ui-lib",
  "sideEffects": false
}

• Barrel file optimization: Turbopack can skip unused re-exports from barrel files (index.ts) when the package declares "sideEffects": false
• Dynamic imports: import() expressions create async chunk boundaries — Turbopack splits these into separate chunks automatically

Diagnosing large bundles

Next.js Bundle Analyzer (Next.js 16.1+, experimental): Integrated with Turbopack's module graph — inspect server and client modules with precise import tracing:

npx next experimental-analyze

Add --output to write the analysis to .next/diagnostics/analyze for sharing or diffing.

Legacy @next/bundle-analyzer: Still works as a fallback:

ANALYZE=true next build

// next.config.ts
import withBundleAnalyzer from '@next/bundle-analyzer'

const nextConfig = withBundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
})({
  // your config
})

Custom Loader Migration from Webpack

Turbopack runs many webpack loaders through turbopack.rules (only a core subset of the loader API is implemented, and only loaders that return JavaScript are supported; webpack plugins are not supported). Here is how to migrate common patterns:

Webpack Loader	Turbopack Equivalent
css-loader + style-loader	Built-in CSS support — remove loaders
sass-loader	Built-in — install sass package
postcss-loader	Built-in — reads postcss.config.js
file-loader / url-loader	Built-in static asset handling
svgr / @svgr/webpack	Use @svgr/webpack via turbopack.rules
raw-loader	Use raw-loader via turbopack.rules (or per import: with { turbopackLoader: 'raw-loader', turbopackAs: '*.js' }, Next.js 16.2+)
graphql-tag/loader	Use graphql-tag/loader via turbopack.rules (tested with Turbopack)
worker-loader	Use native new Worker(new URL(...)) syntax

Configuring custom rules (loader replacement)

For loaders that have no built-in equivalent, use turbopack.rules:

// next.config.ts
const nextConfig: NextConfig = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}

When migration isn't possible

If a webpack loader has no Turbopack equivalent and no workaround, fall back to webpack with the CLI flag:

next dev --webpack
next build --webpack

File an issue at github.com/vercel/next.js — the Turbopack team tracks loader parity requests.

Production Build Diagnostics

Build failing with Turbopack

1. Check for unsupported config: Remove any webpack() function from next.config — it's ignored by Turbopack and may mask the real config
2. Verify turbopack.rules: Ensure custom rules reference valid loaders that are installed
3. Check for Node.js built-in usage in edge/client: Turbopack enforces environment boundaries — fs, path, etc. cannot be imported in client or edge bundles
4. Module not found errors: Ensure turbopack.resolveAlias covers any custom resolution that was previously in webpack config

Build output too large

• Audit "use client" directives — each client component boundary creates a new chunk
• Check for accidentally bundled server-only packages in client components
• Use server-only package to enforce server/client boundaries at import time:

npm install server-only

// lib/db.ts
import 'server-only' // Build fails if imported in a client component

Comparing webpack vs Turbopack output

Run both bundlers and compare:

# Turbopack build (default in Next.js 16)
next build

# Webpack build
next build --webpack

Compare .next/ output sizes and page-level chunks.

Performance Profiling

Turbopack tracing

Generate a trace file for dev or build performance issues:

next dev --internal-trace

Reproduce the issue, then stop the server — a trace-turbopack.bin file is written to the .next-profiles directory. Interpret it with npx next internal trace .next-profiles/trace-turbopack.bin and view it at trace.nextjs.org. The same flag works with next build --internal-trace.

Look for:

• Long-running transforms: Indicates a slow SWC plugin or heavy PostCSS config
• Large module graphs: Reduce barrel file re-exports
• Cache misses: If incremental builds aren't hitting cache, check for files that change every build (e.g., generated timestamps)

Memory usage

Turbopack's Rust core manages its own memory. If builds OOM:

• Increase Node.js heap: NODE_OPTIONS='--max-old-space-size=8192' next build
• Reduce concurrent tasks if running inside Turborepo: turbo build --concurrency=2

Turbopack vs Webpack

Feature	Turbopack	Webpack
Language	Rust	JavaScript
HMR speed	Constant (O(1))	Degrades with app size
RSC support	Native	Plugin-based
Cold start	Fast	Slower
Ecosystem	Growing	Massive (loaders, plugins)
Status in Next.js 16	Default	Still supported
Tree shaking	Module-level	Module-level
CSS handling	Built-in	Requires loaders
Production builds	Supported	Supported

When You Might Need Webpack

• Custom webpack loaders with no Turbopack equivalent
• Complex webpack plugin configurations (e.g., ModuleFederationPlugin)
• Specific webpack features not yet in Turbopack (e.g., custom externals functions)
• Turbopack does not support webpack plugins at all (only a subset of loaders)

To use webpack instead, pass the --webpack flag (there is no next.config.js option to opt out):

next dev --webpack
next build --webpack

Development vs Production

• Development: Turbopack provides instant HMR and fast refresh
• Production: Turbopack handles the production build (replaces webpack in Next.js 16)

Common Issues

1. Missing loader equivalent: Some webpack loaders don't have Turbopack equivalents yet. Check Turbopack docs for supported transformations.
2. Config migration: Move experimental.turbo to top-level turbopack in next.config.
3. Custom aliases: Use turbopack.resolveAlias instead of webpack.resolve.alias.
4. CSS ordering changes: Test visual regressions when migrating — CSS chunk order may differ.
5. Environment boundary errors: Server-only modules imported in client components fail at build time — use server-only package.

Official Documentation

• Turbopack
• Next.js Turbopack Config
• GitHub: Turbopack