Pre-Filled Template
SKILL.md
--- name: nextjs-turbopack description: Next.js 16+ and Turbopack guidance — incremental Rust bundling, file-system caching, faster dev startup and HMR, Turbopack vs webpack tradeoffs, and the middleware.ts to proxy.ts filename change. Use when developing or debugging Next.js 16+ apps, diagnosing slow dev startup or hot reload, choosing between bundlers, or reviewing middleware/proxy file naming. metadata: 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. ## 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. - **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). ## Examples ### Commands ```bash next dev next build next start ``` ### Usage 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. ## Middleware File Naming Next.js 16 introduced `proxy.ts` as the middleware filename, replacing the older `middleware.ts` convention: - **Next.js 16+**: use `proxy.ts` at the project root - **Pre-Next.js 16**: use `middleware.ts` at the project root The filename change is tied to the **Next.js version**, not to which bundler (Turbopack or webpack) is in use. Always check the official docs for the version you are reviewing. **Do not flag `proxy.ts` as a misnamed or missing middleware file in Next.js 16 projects.** The file is correct and intentional. Suggesting a rename to `middleware.ts` will break middleware execution. Reference: [Next.js proxy docs](https://nextjs.org/docs/app/getting-started/proxy) ## 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 official Next.js bundle analysis tooling for your version.
