Otimizando Code Splitting e Lazy Loading com Claude Code

Defina primeiro o limite da divisão

Code splitting não significa dividir todos os arquivos. O objetivo é carregar no primeiro acesso apenas o que sustenta confiança e conversão: título, preço, CTA e formulário principal. Componentes pesados, como gráficos, mapa, editor rico, painel administrativo e vídeo, podem ser carregados depois.

Leia também otimização de performance, Next.js fullstack e testes com Playwright. As referências oficiais são React lazy e Next.js dynamic imports.

Organize primeiro os termos

Um bundle é o pacote de JavaScript enviado ao navegador. Um chunk é cada arquivo menor gerado após a divisão de código. O dynamic import, como import("./Chart"), é o mecanismo que carrega um módulo em tempo de execução. O Suspense é a fronteira que mostra uma UI de carregamento no lugar de um componente que ainda está sendo baixado.

A hydration é o processo em que o JavaScript do navegador reconecta eventos e estado ao HTML que o servidor retornou. Se a exibição do servidor e a do cliente divergirem aqui, ocorre um hydration error. O lazy loading é prático, mas misturar lógica que só roda no navegador, hora atual, números aleatórios ou referências a window facilita esse descompasso. Por isso, mantenha os valores específicos do navegador dentro de um Client Component ou leia-os apenas depois do useEffect.

Prompt para Claude Code

Analise esta página React/Next.js e proponha code splitting seguro.
Não atrase título, preço, CTA ou formulário principal.
Considere lazy load para gráficos, editor, mapa, painel admin e vídeo.
Retorne código com lazy/Suspense ou dynamic import, fallback UI, error boundary e checklist.

Use case checklist

1. Artigos: corpo e CTA primeiro; comentários, busca e painel de compartilhamento depois.
2. Dashboard SaaS: KPIs primeiro; gráficos detalhados e exportação depois.
3. Admin: permissões, logs e configurações podem ser separados por rota.
4. Ecommerce: produto e compra primeiro; recomendações, reviews e vídeo depois.

Código de implementação

import { lazy, Suspense } from "react";

const HeavyChart = lazy(() => import("./HeavyChart"));

export function DashboardPanel() {
  return (
    <section>
      <h2>Revenue overview</h2>
      <Suspense fallback={<p role="status">Loading chart...</p>}>
        <HeavyChart />
      </Suspense>
    </section>
  );
}

import dynamic from "next/dynamic";

const RichTextEditor = dynamic(() => import("../components/RichTextEditor"), {
  loading: () => <p role="status">Loading editor...</p>,
  ssr: false,
});

Repare que lazy espera um default export. Um arquivo que só tem named export não funciona ao ser carregado direto; nesse caso, reembrulhe o módulo para default depois do carregamento. E ssr: false é útil, mas não deve ser usado em texto necessário para SEO ou em descrições de produto, porque o conteúdo deixa de aparecer no HTML do servidor e nem o leitor nem o buscador veem a informação importante no primeiro acesso.

Pitfall checklist

• Colocar o CTA em lazy load reduz conversão.
• Fallback sem altura estável cria layout shift.
• Sem error boundary, uma falha no chunk pode deixar a tela vazia.
• Divisão excessiva aumenta requests e pode piorar redes lentas.
• Verifique production build; dev server engana.

Cuidado com a divisão excessiva e o hydration mismatch

A primeira armadilha é dividir demais. Quando surgem muitos chunks pequenos, a espera de rede aumenta e a página parece mais lenta. Peça ao Claude Code para verificar não só “quantos KB saíram do bundle inicial”, mas também “quantas requisições foram adicionadas” e “qual o tempo de espera depois da ação do usuário”.

A segunda armadilha é o hydration mismatch. Ele acontece quando a exibição diverge entre servidor e cliente, por exemplo “não logado” no servidor e “logado” no cliente, ou hora A no servidor e hora B no cliente. A terceira é fazer lazy load até das rotas de SEO e receita. Colocar título do artigo, texto equivalente à description, preço, CTA e FAQ dentro de ssr: false prejudica tanto a intenção de busca quanto a experiência do leitor. Quanto mais perto da receita estiver a UI, mais ela deve ficar de fora do lazy loading.

Verificação

Rode build, observe Network waterfall e tamanho dos chunks. No mobile 375px, confirme que fallback não quebra layout, code block rola corretamente e CTA continua visível. A review do Claude Code deve listar componentes adiados, motivo, risco e rollback.

Monetização

Code splitting afeta velocidade de anúncios, cards de produto, formulários de consulta e botões de compra. Para levar isso ao time, use treinamento e consultoria Claude Code e transforme a melhoria em processo recorrente.

Ordem de migração

O primeiro passo não é editar código, mas mapear a tela. Peça a Claude Code uma tabela com componentes pesados, componentes essenciais do primeiro viewport, interações que podem esperar e áreas que afetam SEO ou conversão. Depois divida apenas um componente de baixo risco, como gráfico ou editor. Só então avalie divisão por rota. Essa sequência mantém o diff pequeno e facilita rollback.

Template de review em equipe

• Qual componente foi carregado depois e por quê.
• Se o fallback tem altura estável e não gera layout shift.
• Se CTA, preço, formulário e anúncio continuam visíveis no primeiro carregamento.
• O que o usuário vê quando o chunk falha ou a rede está lenta.
• Se o production build mostra chunks menores e compreensíveis.

Métricas operacionais

Não julgue apenas por Lighthouse. Observe tempo na página, clique no CTA, viewability de anúncios, chegada ao formulário e taxa de conversão. Se o JavaScript cai, mas a rota de receita piora, a mudança não foi boa. Claude Code deve revisar performance e negócio no mesmo checklist.

Nota prática

Testei mantendo o CTA inicial e adiando apenas gráfico e editor. O resultado foi mais fácil de revisar do que dividir tudo, e a rota de conversão permaneceu protegida. O efeito apareceu quando, antes de escrever código, defini “manter o primeiro viewport e o CTA”, “separar só as dependências pesadas” e “conferir os chunks no Network”. Quando apenas pedi ao Claude Code “faça lazy loading”, o escopo do Suspense ficou largo demais e o ssr: false entrou em lugares desnecessários.