/turbopack

name: turbopack
description: Turbopack expert guidance. Use when configuring the Next.js bundler, optimizing HMR, debugging build issues, or understanding the Turbopack vs Webpack differences.
metadata:
  priority: 4
  docs:
    - "https://nextjs.org/docs/app/api-reference/turbopack"
    - "https://nextjs.org/docs/app/api-reference/config/next-config-js/turbopack"
  sitemap: "https://nextjs.org/sitemap.xml"
  pathPatterns: 
    - 'next.config.*'
  bashPatterns: 
    - '\bnext\s+dev\s+--turbo\b'
    - '\bnext\s+dev\s+--turbopack\b'
retrieval:
  aliases:
    - next bundler
    - turbopack
    - fast bundler
    - hmr
  intents:
    - enable turbopack
    - fix build issue
    - speed up dev server
    - configure bundler
  entities:
    - Turbopack
    - HMR
    - bundler
    - next dev --turbopack
chainTo:
  -
    pattern: 'webpack\s*:\s*\(|webpack\s*\(config'
    targetSkill: nextjs
    message: 'Webpack config detected — loading Next.js guidance for migrating webpack customizations to Turbopack top-level config in Next.js 16.'
  -
    pattern: 'turbopack\s*:\s*\{|experimental\.turbo\b'
    targetSkill: nextjs
    message: 'Turbopack configuration detected — loading Next.js guidance for top-level turbopack config syntax in Next.js 16 (moved from experimental.turbo).'

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`