Labsco
vercel logo

turbopack

✓ Official★ 207

by vercel · part of vercel/vercel-plugin

Turbopack expert guidance. Use when configuring the Next.js bundler, optimizing HMR, debugging build issues, or understanding the Turbopack vs Webpack…

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#git
🔌 This skill ships inside the vercel plugin — install the plugin and you also get 5 slash commands, 3 sub-agents, hooks, an MCP server.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

by vercel

Turbopack expert guidance. Use when configuring the Next.js bundler, optimizing HMR, debugging build issues, or understanding the Turbopack vs Webpack… npx skills add https://github.com/vercel/vercel-plugin --skill turbopack Download ZIPGitHub207

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

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 {children} 
}

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

Built-in analyzer (Next.js 16.1+, experimental): Works natively with Turbopack. Offers route-specific filtering, import tracing, and RSC boundary analysis:

// next.config.ts
const nextConfig: NextConfig = {
 experimental: {
 bundleAnalyzer: true,
 },
}

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 does not support webpack loaders directly. 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 import x from './file?raw' graphql-tag/loader Use a build-time codegen step instead 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:

const nextConfig: NextConfig = {
 bundler: 'webpack',
}

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

Production Build Diagnostics

Build failing with Turbopack

  • Check for unsupported config: Remove any webpack() function from next.config — it's ignored by Turbopack and may mask the real config

  • Verify turbopack.rules: Ensure custom rules reference valid loaders that are installed

  • 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

  • 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
BUNDLER=webpack next build

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

Performance Profiling

HMR profiling

Enable verbose HMR timing in development:

NEXT_TURBOPACK_TRACING=1 next dev

This writes a trace.json to the project root — open it in chrome://tracing or Perfetto to see module-level timing.

Build profiling

Profile production builds:

NEXT_TURBOPACK_TRACING=1 next build

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)

To use webpack instead:

// next.config.ts
const nextConfig: NextConfig = {
 bundler: 'webpack', // Opt out of Turbopack
}

Development vs Production

  • Development: Turbopack provides instant HMR and fast refresh

  • Production: Turbopack handles the production build (replaces webpack in Next.js 16)

Official Documentation