turbopack
Turbopack expert guidance. Use when configuring the Next.js bundler, optimizing HMR, debugging build issues, or understanding the Turbopack vs Webpack differences.
- License 许可
- MIT
- 最近更新
- 2026-03-27
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- turbopack
- chainTo
- [ { "message": "Webpack config detected — loading Next.js guidance for migrating webpack customizations to Turbopack top-level config in Next.js 16.", "pattern": "webpack\\s*:\\s*\\(|webpack\\s*\\(config", "targetSkill": "nextjs" }, { "message": "Turbopack configuration detected — loading Next.js guidance for top-level turbopack config syntax in Next.js 16 (moved from experimental.turbopack).", "pattern": "turbopack\\s*:\\s*\\{|experimental\\.turbopack", "targetSkill": "nextjs" } ]
- metadata
- { "docs": [ "https://turbo.build/pack/docs", "https://nextjs.org/docs/architecture/turbopack" ], "sitemap": "https://turbo.build/sitemap.xml", "priority": 4, "bashPatterns": [ "\\bnext\\s+dev\\s+--turbo\\b", "\\bnext\\s+dev\\s+--turbopack\\b" ], "pathPatterns": [ "next.config.*" ] }
- 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" ] }
- description
- Turbopack expert guidance. Use when configuring the Next.js bundler, optimizing HMR, debugging build issues, or understanding the Turbopack vs Webpack differences.
02 资源文件 1
- 参考文档_AIWF_IMPORT.json372 B
03 SKILL.md 正文
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):
// 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.
@importin global CSS: Use standard CSS@import— Turbopack resolves them, but circular imports cause build failures.- CSS-in-JS libraries:
styled-componentsandemotionwork but require their SWC plugins configured undercompilerin 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
exporton each function/constant rather than barrelexport * - Side-effect-free packages: Mark packages as side-effect-free in
package.jsonto 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.resolveAliascovers 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-onlypackage 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
externalsfunctions)
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)
Common Issues
- Missing loader equivalent: Some webpack loaders don't have Turbopack equivalents yet. Check Turbopack docs for supported transformations.
- Config migration: Move
experimental.turbopackto top-levelturbopackin next.config. - Custom aliases: Use
turbopack.resolveAliasinstead ofwebpack.resolve.alias. - CSS ordering changes: Test visual regressions when migrating — CSS chunk order may differ.
- Environment boundary errors: Server-only modules imported in client components fail at build time — use
server-onlypackage.
Official Documentation
04 同仓库更多 Skills
zustand
Zustand state management guide. Use when working with store code (src/store/**), implementing actions, managing state, or creating slices. Triggers on Zustand store development, state management questions, or action implementation.
web-vitals
暂无简介
vercel-storage
Vercel storage expert guidance — Blob, Edge Config, and Marketplace storage (Neon Postgres, Upstash Redis). Use when choosing, configuring, or using data storage with Vercel applications.
vercel-functions
Vercel Functions expert guidance — Serverless Functions, Edge Functions, Fluid Compute, streaming, Cron Jobs, and runtime configuration. Use when configuring, debugging, or optimizing server-side code running on Vercel.
ui-ux-pro-max
UI/UX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and HTML/CSS). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, and check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, and mobile app. Elements: button, modal, navbar, sidebar, card, table, form, and chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, and flat design. Topics: color systems, accessibility, animation, layout, typography, font pairing, spacing, interaction states, shadow, and gradient. Integrations: shadcn/ui MCP for component search and examples.
turborepo
Turborepo monorepo build system guidance. Triggers on: turbo.json, task pipelines, dependsOn, caching, remote cache, the "turbo" CLI, --filter, --affected, CI optimization, environment variables, internal packages, monorepo structure/best practices, and boundaries. Use when user: configures tasks/workflows/pipelines, creates packages, sets up monorepo, shares code between apps, runs changed/affected packages, debugs cache, or has apps/packages directories.