Turbopack

# 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 (Stable)**: Dev server artifacts cached on disk between restarts — up to 14x faster startup on large projects. Enabled by default in Next.js 16.1+, no config needed. Build caching planned next.
- **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.turbopack`):

```js
// 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:

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

### CSS Modules

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

```tsx
// 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:

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

### Sass / SCSS

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

```bash
npm install sass
```

```tsx
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