AGENT SKILL

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

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.
  • @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

  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
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)

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.turbopack 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

04 同仓库更多 Skills

ByeongminLee
ByeongminLee/nextjs-claude-code

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.

★ 3
ByeongminLee
ByeongminLee/nextjs-claude-code

web-vitals

暂无简介

★ 3
ByeongminLee
ByeongminLee/nextjs-claude-code

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.

后端与接口
★ 3
ByeongminLee
ByeongminLee/nextjs-claude-code

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.

开发工程师后端与接口
★ 3
ByeongminLee
ByeongminLee/nextjs-claude-code

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.

设计师数据分析师前端开发视觉设计
★ 3
ByeongminLee
ByeongminLee/nextjs-claude-code

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.

★ 3