Package Bundling

Core Idea

Next.js já otimiza bundles automaticamente (code splitting, tree-shaking); pra casos manuais, dois analisadores (Turbopack Bundle Analyzer experimental e @next/bundle-analyzer pra Webpack) ajudam a achar dependências grandes, e config específica resolve os padrões mais comuns de bloat.

Key Concepts

• next experimental-analyze (v16.1+): analisador integrado ao module graph do Turbopack, com filtro por rota/ambiente (client/server)/tipo e rastreamento de import chain; --output salva análise estática em .next/diagnostics/analyze pra comparar antes/depois.
• @next/bundle-analyzer: plugin Webpack tradicional, ativado via ANALYZE=true, gera relatório visual em três abas do browser.
• optimizePackageImports: opção experimental que carrega só os módulos realmente usados de libs com centenas de exports (ícones, utilitários), mantendo a conveniência de named imports; várias libs populares já são otimizadas automaticamente sem precisar listar.
• Mover trabalho pesado pro servidor: libs que só transformam dado em UI (syntax highlight, markdown, charts) devem rodar em Server Component quando não dependem de API de browser, evitando embarcar a lib inteira no bundle client.
• transpilePackages: força bundling de pacotes externos não pré-bundlados (comuns em monorepo ou vindos de node_modules).
• bundlePagesRouterDependencies: bundla automaticamente todos os pacotes externos (default false).
• serverExternalPackages: opt-out de pacotes específicos do bundling automático, mesmo com bundlePagesRouterDependencies: true.

Code Examples

const nextConfig = {
  experimental: {
    optimizePackageImports: ['icon-library'],
  },
}

• O que demonstra: import otimizado de lib com muitos exports nomeados.

import { codeToHtml } from 'shiki'

export default async function Page() {
  const highlightedHtml = await codeToHtml(code, { lang: 'tsx', theme: 'github-dark' })
  return <pre><code dangerouslySetInnerHTML={{ __html: highlightedHtml }} /></pre>
}

• O que demonstra: syntax highlighting rodando no servidor (Shiki), enviando só HTML pro client, em vez de bundlar a lib inteira (prism-react-renderer) num Client Component.

const nextConfig = {
  bundlePagesRouterDependencies: true,
  serverExternalPackages: ['package-name'],
}

• O que demonstra: bundling automático geral com exceção pontual pra um pacote específico.

Reference Tables

Opção	Efeito
optimizePackageImports	Só carrega módulos usados de libs com muitos exports
transpilePackages	Força bundling de pacotes externos específicos
bundlePagesRouterDependencies	Bundla automaticamente todos os pacotes externos (default false)
serverExternalPackages	Opt-out de pacotes específicos do bundling automático

Anti-patterns

• Renderizar highlight/chart/markdown em Client Component sem necessidade: embarca a lib inteira no bundle do client mesmo quando o resultado é HTML estático; mover pra Server Component quando não depende de browser API.
• Ignorar dependência de monorepo não pré-bundlada: sem transpilePackages, pode gerar erro ou bundle ineficiente.

Key Takeaways

1. Sempre analisar antes de otimizar às cegas: next experimental-analyze (Turbopack) ou @next/bundle-analyzer (Webpack).
2. Trabalho de transformação de dado-pra-UI que não precisa de browser deve rodar em Server Component.
3. optimizePackageImports resolve o caso comum de libs de ícones/utilitários com muitos exports.
4. serverExternalPackages é a válvula de escape quando bundling automático (bundlePagesRouterDependencies) causa problema num pacote específico.

Connects To

• ch308 Lazy Loading: técnica complementar de redução de bundle via code-splitting sob demanda.