turbopackChunking

Core Idea

Experimental config (experimental.turbopackChunking) that tunes how Turbopack splits client-side JS into chunks in production — trade-off between initial page load performance and navigation performance.

Key Concepts

• minChunkSize (default 50000): avoids more than one chunk smaller than this size by merging; higher = fewer/larger chunks.
• maxChunkCountPerGroup (default 40): max chunks per chunk group (route or dynamic import); lower = more aggressive merging.
• maxMergeChunkSize (default 200000): a chunk larger than this is never merged with others.
• clusters: array of RegExp arrays grouping routes commonly visited together; chunks shared within a cluster merge more eagerly.
• firstPageLoadPriority (0-1): weight given to first page load benefit; higher merges more eagerly.
• priorityRoutes / priorityBoost (default 1.5): routes likely to be entry points get their bundles merged more aggressively.
• requestCost (default 200000): estimated cost in bytes of an extra request; higher biases toward fewer/larger chunks.

Code Examples

const nextConfig = {
  experimental: {
    turbopackChunking: {
      minChunkSize: 50000,
      maxChunkCountPerGroup: 40,
      maxMergeChunkSize: 200000,
    },
  },
} satisfies NextConfig

• O que demonstra: valores default do chunker de produção do Turbopack.

Anti-patterns

• Usar em produção sem testar: feature experimental, sujeita a mudanças; não recomendada pra produção.

Key Takeaways

1. Sizes são em bytes de código não-minificado (~5x o tamanho do output minificado/comprimido).
2. Merging melhora load inicial mas piora performance de navegação (mais bytes por request, menos cache hits).
3. clusters e priorityRoutes deixam você ensinar o chunker sobre padrões reais de navegação do seu site.

Connects To

• turbopack (ch420): config irmã pra loaders/resolução; esta é específica de chunking de produção.