nextjs-turbopack · diff
git:20260316.f03db82 to git:20260316.0be6455
17 added, 33 removed. Audit A to A.
---
name: nextjs-turbopack
description: Next.js 16+ and Turbopack — incremental bundling, FS caching, dev speed, and when to use Turbopack vs webpack.
origin: ECC
---
# Next.js and Turbopack
- Next.js 16+ uses Turbopack by default for local development: an incremental bundler written in Rust that significantly speeds up dev startup and hot updates. Use this skill when working with Next.js 16+ or tuning build performance.
+ Next.js 16+ uses Turbopack by default for local development: an incremental bundler written in Rust that significantly speeds up dev startup and hot updates.
- ## Core Concepts
+ ## When to Use
+ - **Turbopack (default dev)**: Use for day-to-day development. Faster cold start and HMR, especially in large apps.
+ - **Webpack (legacy dev)**: Use only if you hit a Turbopack bug or rely on a webpack-only plugin in dev. Disable with `--webpack` (or `--no-turbopack` depending on your Next.js version; check the docs for your release).
+ - **Production**: Production build behavior (`next build`) may use Turbopack or webpack depending on Next.js version; check the official Next.js docs for your version.
+
+ Use when: developing or debugging Next.js 16+ apps, diagnosing slow dev startup or HMR, or optimizing production bundles.
+
+ ## How It Works
+
- **Turbopack**: Incremental bundler for Next.js dev. Uses file-system caching so restarts are much faster (e.g. 5–14x on large projects).
- **Default in dev**: From Next.js 16, `next dev` runs with Turbopack unless disabled.
- - **Production**: Next.js production builds still use the existing production bundler (webpack-based); Turbopack is focused on dev today.
-
- ## When to Use Turbopack vs Webpack
+ - **File-system caching**: Restarts reuse previous work; cache is typically under `.next`; no extra config needed for basic use.
+ - **Bundle Analyzer (Next.js 16.1+)**: Experimental Bundle Analyzer to inspect output and find heavy dependencies; enable via config or experimental flag (see Next.js docs for your version).
- - **Turbopack (default dev)**: Use for day-to-day development. Faster cold start and HMR, especially in large apps.
- - **Webpack (legacy dev)**: Use only if you hit a Turbopack bug or rely on a webpack-only plugin in dev. Disable with env or flag (e.g. `--no-turbopack` if your version supports it).
- - **Production**: No change; production build pipeline is unchanged.
+ ## Examples
- ## Commands
+ ### Commands
```bash
- # Dev with Turbopack (Next.js 16+ default)
next dev
-
- # Build (unchanged; not Turbopack)
next build
-
- # Start production server
next start
```
- ## File-System Caching
-
- Turbopack caches work on disk so that:
-
- - Restarts reuse previous work; second run is much faster.
- - Large projects see 5–14x faster compile times on restart in practice.
- - Cache is typically under `.next` or a similar project-local directory; no extra config needed for basic use.
-
- ## Bundle Analyzer (Next.js 16.1+)
-
- Next.js 16.1 introduced an experimental Bundle Analyzer to inspect output and find heavy dependencies:
+ ### Usage
- - Enable via config or experimental flag (see Next.js docs for your version).
- - Use to optimize code-splitting and trim large dependencies.
+ Run `next dev` for local development with Turbopack. Use the Bundle Analyzer (see Next.js docs) to optimize code-splitting and trim large dependencies. Prefer App Router and server components where possible.
## Best Practices
- Stay on a recent Next.js 16.x for stable Turbopack and caching behavior.
- If dev is slow, ensure you're on Turbopack (default) and that the cache isn't being cleared unnecessarily.
- - For production bundle size issues, use the Bundle Analyzer and `next/bundle-analysis` or equivalent tooling.
- - Prefer App Router and server components where possible; they align with current Next.js and Turbopack optimizations.
-
- ## When to Use This Skill
-
- Use when: developing or debugging Next.js 16+ apps, diagnosing slow dev startup or HMR, or optimizing production bundles with Next.js tooling.
+ - For production bundle size issues, use the official Next.js bundle analysis tooling for your version.