Update to Vercel

{
  "name": "turbopack",
  "description": "Turbopack expert guidance. Use when configuring the Next.js bundler, optimizing HMR, debugging build issues, or understanding the Turbopack vs Webpack differences.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 88
    }
  ],
  "skill_md_contents": "---\nname: turbopack\ndescription: Turbopack expert guidance. Use when configuring the Next.js bundler, optimizing HMR, debugging build issues, or understanding the Turbopack vs Webpack differences.\nmetadata:\n  priority: 4\n  docs:\n    - \"https://turbo.build/pack/docs\"\n    - \"https://nextjs.org/docs/architecture/turbopack\"\n  sitemap: \"https://turbo.build/sitemap.xml\"\n  pathPatterns: \n    - 'next.config.*'\n  bashPatterns: \n    - '\\bnext\\s+dev\\s+--turbo\\b'\n    - '\\bnext\\s+dev\\s+--turbopack\\b'\n---\n\n# Turbopack\n\nYou are an expert in Turbopack — the Rust-powered JavaScript/TypeScript bundler built by Vercel. It is the default bundler in Next.js 16.\n\n## Key Features\n\n- **Instant HMR**: Hot Module Replacement that doesn't degrade with app size\n- **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.\n- **Multi-environment builds**: Browser, Server, Edge, SSR, React Server Components\n- **Native RSC support**: Built for React Server Components from the ground up\n- **TypeScript, JSX, CSS, CSS Modules, WebAssembly**: Out of the box\n- **Rust-powered**: Incremental computation engine for maximum performance\n\n## Configuration (Next.js 16)\n\nIn Next.js 16, Turbopack config is top-level (moved from `experimental.turbopack`):\n\n```js\n// next.config.ts\nimport type { NextConfig } from 'next'\n\nconst nextConfig: NextConfig = {\n  turbopack: {\n    // Resolve aliases (like webpack resolve.alias)\n    resolveAlias: {\n      'old-package': 'new-package',\n    },\n    // Custom file extensions to resolve\n    resolveExtensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],\n  },\n}\n\nexport default nextConfig\n```\n\n## CSS and CSS Modules Handling\n\nTurbopack handles CSS natively without additional configuration.\n\n### Global CSS\n\nImport global CSS in your root layout:\n\n```tsx\n// app/layout.tsx\nimport './globals.css'\n```\n\n### CSS Modules\n\nCSS Modules work out of the box with `.module.css` files:\n\n```tsx\n// components/Button.tsx\nimport styles from './Button.module.css'\n\nexport function Button({ children }) {\n  return <button className={styles.primary}>{children}</button>\n}\n```\n\n### PostCSS\n\nTurbopack reads your `postcss.config.js` automatically. Tailwind CSS v4 works with zero config:\n\n```js\n// postcss.config.js\nmodule.exports = {\n  plugins: {\n    '@tailwindcss/postcss': {},\n    autoprefixer: {},\n  },\n}\n```\n\n### Sass / SCSS\n\nInstall `sass` and import `.scss` files directly — Turbopack compiles them natively:\n\n```bash\nnpm install sass\n```\n\n```tsx\nimport styles from './Component.module.scss'\n```\n\n### Common CSS pitfalls\n\n- **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.\n- **`@import` in global CSS**: Use standard CSS `@import` — Turbopack resolves them, but circular imports cause build failures.\n- **CSS-in-JS libraries**: `styled-components` and `emotion` work but require their SWC plugins configured under `compiler` in next.config.\n\n## Tree Shaking\n\nTurbopack performs tree shaking at the module level in production builds. Key behaviors:\n\n- **ES module exports**: Only used exports are included — write `export` on each function/constant rather than barrel `export *`\n- **Side-effect-free packages**: Mark packages as side-effect-free in `package.json` to enable aggressive tree shaking:\n\n```json\n{\n  \"name\": \"my-ui-lib\",\n  \"sideEffects\": false\n}\n```\n\n- **Barrel file optimization**: Turbopack can skip unused re-exports from barrel files (`index.ts`) when the package declares `\"sideEffects\": false`\n- **Dynamic imports**: `import()` expressions create async chunk boundaries — Turbopack splits these into separate chunks automatically\n\n### Diagnosing large bundles\n\n**Built-in analyzer (Next.js 16.1+, experimental)**: Works natively with Turbopack. Offers route-specific filtering, import tracing, and RSC boundary analysis:\n\n```ts\n// next.config.ts\nconst nextConfig: NextConfig = {\n  experimental: {\n    bundleAnalyzer: true,\n  },\n}\n```\n\n**Legacy `@next/bundle-analyzer`**: Still works as a fallback:\n\n```bash\nANALYZE=true next build\n```\n\n```ts\n// next.config.ts\nimport withBundleAnalyzer from '@next/bundle-analyzer'\n\nconst nextConfig = withBundleAnalyzer({\n  enabled: process.env.ANALYZE === 'true',\n})({\n  // your config\n})\n```\n\n## Custom Loader Migration from Webpack\n\nTurbopack does not support webpack loaders directly. Here is how to migrate common patterns:\n\n| Webpack Loader | Turbopack Equivalent |\n|----------------|---------------------|\n| `css-loader` + `style-loader` | Built-in CSS support — remove loaders |\n| `sass-loader` | Built-in — install `sass` package |\n| `postcss-loader` | Built-in — reads `postcss.config.js` |\n| `file-loader` / `url-loader` | Built-in static asset handling |\n| `svgr` / `@svgr/webpack` | Use `@svgr/webpack` via `turbopack.rules` |\n| `raw-loader` | Use `import x from './file?raw'` |\n| `graphql-tag/loader` | Use a build-time codegen step instead |\n| `worker-loader` | Use native `new Worker(new URL(...))` syntax |\n\n### Configuring custom rules (loader replacement)\n\nFor loaders that have no built-in equivalent, use `turbopack.rules`:\n\n```js\n// next.config.ts\nconst nextConfig: NextConfig = {\n  turbopack: {\n    rules: {\n      '*.svg': {\n        loaders: ['@svgr/webpack'],\n        as: '*.js',\n      },\n    },\n  },\n}\n```\n\n### When migration isn't possible\n\nIf a webpack loader has no Turbopack equivalent and no workaround, fall back to webpack:\n\n```js\nconst nextConfig: NextConfig = {\n  bundler: 'webpack',\n}\n```\n\nFile an issue at [github.com/vercel/next.js](https://github.com/vercel/next.js) — the Turbopack team tracks loader parity requests.\n\n## Production Build Diagnostics\n\n### Build failing with Turbopack\n\n1. **Check for unsupported config**: Remove any `webpack()` function from next.config — it's ignored by Turbopack and may mask the real config\n2. **Verify `turbopack.rules`**: Ensure custom rules reference valid loaders that are installed\n3. **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\n4. **Module not found errors**: Ensure `turbopack.resolveAlias` covers any custom resolution that was previously in webpack config\n\n### Build output too large\n\n- Audit `\"use client\"` directives — each client component boundary creates a new chunk\n- Check for accidentally bundled server-only packages in client components\n- Use `server-only` package to enforce server/client boundaries at import time:\n\n```bash\nnpm install server-only\n```\n\n```ts\n// lib/db.ts\nimport 'server-only' // Build fails if imported in a client component\n```\n\n### Comparing webpack vs Turbopack output\n\nRun both bundlers and compare:\n\n```bash\n# Turbopack build (default in Next.js 16)\nnext build\n\n# Webpack build\nBUNDLER=webpack next build\n```\n\nCompare `.next/` output sizes and page-level chunks.\n\n## Performance Profiling\n\n### HMR profiling\n\nEnable verbose HMR timing in development:\n\n```bash\nNEXT_TURBOPACK_TRACING=1 next dev\n```\n\nThis writes a `trace.json` to the project root — open it in `chrome://tracing` or [Perfetto](https://ui.perfetto.dev/) to see module-level timing.\n\n### Build profiling\n\nProfile production builds:\n\n```bash\nNEXT_TURBOPACK_TRACING=1 next build\n```\n\nLook for:\n- **Long-running transforms**: Indicates a slow SWC plugin or heavy PostCSS config\n- **Large module graphs**: Reduce barrel file re-exports\n- **Cache misses**: If incremental builds aren't hitting cache, check for files that change every build (e.g., generated timestamps)\n\n### Memory usage\n\nTurbopack's Rust core manages its own memory. If builds OOM:\n- Increase Node.js heap: `NODE_OPTIONS='--max-old-space-size=8192' next build`\n- Reduce concurrent tasks if running inside Turborepo: `turbo build --concurrency=2`\n\n## Turbopack vs Webpack\n\n| Feature | Turbopack | Webpack |\n|---------|-----------|---------|\n| Language | Rust | JavaScript |\n| HMR speed | Constant (O(1)) | Degrades with app size |\n| RSC support | Native | Plugin-based |\n| Cold start | Fast | Slower |\n| Ecosystem | Growing | Massive (loaders, plugins) |\n| Status in Next.js 16 | Default | Still supported |\n| Tree shaking | Module-level | Module-level |\n| CSS handling | Built-in | Requires loaders |\n| Production builds | Supported | Supported |\n\n## When You Might Need Webpack\n\n- Custom webpack loaders with no Turbopack equivalent\n- Complex webpack plugin configurations (e.g., `ModuleFederationPlugin`)\n- Specific webpack features not yet in Turbopack (e.g., custom `externals` functions)\n\nTo use webpack instead:\n```js\n// next.config.ts\nconst nextConfig: NextConfig = {\n  bundler: 'webpack', // Opt out of Turbopack\n}\n```\n\n## Development vs Production\n\n- **Development**: Turbopack provides instant HMR and fast refresh\n- **Production**: Turbopack handles the production build (replaces webpack in Next.js 16)\n\n## Common Issues\n\n1. **Missing loader equivalent**: Some webpack loaders don't have Turbopack equivalents yet. Check Turbopack docs for supported transformations.\n2. **Config migration**: Move `experimental.turbopack` to top-level `turbopack` in next.config.\n3. **Custom aliases**: Use `turbopack.resolveAlias` instead of `webpack.resolve.alias`.\n4. **CSS ordering changes**: Test visual regressions when migrating — CSS chunk order may differ.\n5. **Environment boundary errors**: Server-only modules imported in client components fail at build time — use `server-only` package.\n\n## Official Documentation\n\n- [Turbopack](https://turborepo.dev/pack)\n- [Turbopack Documentation](https://turborepo.dev/pack/docs)\n- [Next.js Turbopack Config](https://nextjs.org/docs/app/api-reference/config/next-config-js/turbopack)\n- [GitHub: Turbopack](https://github.com/vercel/turborepo)\n"
}