Capítulo 251 de 456

turbopackChunking

Core Idea

experimental.turbopackChunking afina o chunker de JavaScript de produção do Turbopack: quanto ele mescla chunks pequenos, tamanho máximo de chunks mesclados, e heurísticas sobre padrões de navegação do usuário, além do recurso experimental de "component chunks".

Key Concepts

  • minChunkSize (default 50000 bytes, código não-comprimido/não-minificado): Turbopack evita ter mais de um chunk menor que isso, mesclando chunks pequenos em maiores.
  • maxChunkCountPerGroup (default 40): limite de chunks por grupo (rota ou dynamic import).
  • maxMergeChunkSize (default 200000): nunca mescla um chunk maior que isso com outros, evita duplicação de código em múltiplos chunks grandes.
  • Component chunks (generateComponentChunks, default false): feature experimental que emite chunks constituintes junto com o chunk mesclado, permitindo o runtime baixar só as peças que faltam em vez do arquivo mesclado inteiro.
  • minComponentChunkSize (default 20000): component chunks menores que isso são dobrados em um único componente.
  • clusters (array de arrays de RegExp): grupos de rotas visitadas juntas com frequência; chunks compartilhados dentro de um cluster são mesclados mais agressivamente.
  • firstPageLoadPriority (0 a 1): peso dado ao benefício de mesclar chunks para o carregamento de uma única página.
  • priorityRoutes (array de RegExp) + priorityBoost (default 1.5): rotas de entrada frequentes (ex. homepage) recebem merge mais agressivo do bundle.
  • requestCost (default 200000): custo estimado (em bytes) de uma requisição adicional; valores maiores favorecem menos chunks maiores.

Code Examples

const nextConfig = {
  experimental: {
    turbopackChunking: {
      minChunkSize: 50000,
      maxChunkCountPerGroup: 40,
      maxMergeChunkSize: 200000,
      minComponentChunkSize: 20000,
      generateComponentChunks: false,
    },
  },
} satisfies NextConfig
  • O que demonstra: valores default de todas as opções básicas de chunking.

Anti-patterns

  • Elevar maxChunkCountPerGroup sem medir: aumenta a chance de cache hit em navegação, mas cria mais requisições de rede por página.

Key Takeaways

  1. Trade-off central: mesclar chunks melhora o carregamento inicial da página mas piora performance de navegação subsequente (menos reuso de cache).
  2. component chunks tenta ter os dois lados: benefício de merge no load inicial sem perder reusabilidade em navegações.
  3. clusters e priorityRoutes deixam você ensinar ao chunker padrões reais de navegação do seu app (ex: bounce rate como proxy de firstPageLoadPriority).

Connects To

  • turbopack: config geral do Turbopack (loaders, rules, resolve); chunking é uma sub-área específica de produção.
  • turbopackFileSystemCache: cache persistente que acelera builds subsequentes, complementar ao chunking.
AnteriorturbopackPróximoturbopackFileSystemCache