nextjs-turbopack

Next.js e Turbopack

O Next.js 16+ usa Turbopack por padrão para desenvolvimento local: um empacotador incremental escrito em Rust que acelera significativamente a inicialização do desenvolvimento e as atualizações dinâmicas (HMR).

Quando usar

• Turbopack (desenvolvimento padrão): Use para o desenvolvimento do dia a dia. Inicialização a frio e HMR mais rápidos, especialmente em aplicações grandes.
• Webpack (desenvolvimento legado): Use apenas se encontrar um bug no Turbopack ou depender de um plugin exclusivo do webpack no desenvolvimento. Desative com --webpack (ou --no-turbopack dependendo da sua versão do Next.js; consulte a documentação da sua versão).
• Produção: O comportamento da compilação de produção (next build) pode usar Turbopack ou webpack dependendo da versão do Next.js; verifique a documentação oficial do Next.js para sua versão.

Use quando: estiver desenvolvendo ou depurando aplicações Next.js 16+, diagnosticando inicialização lenta do desenvolvimento ou HMR, ou otimizando bundles de produção.

Como funciona

• Turbopack: Empacotador incremental para desenvolvimento do Next.js. Usa cache baseado em sistema de arquivos para que reinicializações sejam muito mais rápidas (por exemplo, 5 a 14 vezes em projetos grandes).
• Padrão no desenvolvimento: A partir do Next.js 16, next dev executa com Turbopack, a menos que desabilitado.
• Cache do sistema de arquivos: Reinicializações reutilizam trabalho anterior; o cache geralmente fica em .next; nenhuma configuração extra necessária para uso básico.
• Analisador de Bundle (Next.js 16.1+): Analisador de Bundle experimental para inspecionar a saída e encontrar dependências pesadas; ative via configuração ou flag experimental (consulte a documentação do Next.js para sua versão).

Exemplos

Comandos

next dev
next build
next start

Uso

Execute next dev para desenvolvimento local com Turbopack. Use o Analisador de Bundle (consulte a documentação do Next.js) para otimizar a divisão de código e reduzir dependências grandes. Prefira o App Router e componentes de servidor quando possível.

Nome do arquivo de middleware

O Next.js 16 introduziu proxy.ts como o nome do arquivo de middleware, substituindo a convenção anterior middleware.ts:

• Next.js 16+: use proxy.ts na raiz do projeto
• Pré-Next.js 16: use middleware.ts na raiz do projeto

A mudança de nome está vinculada à versão do Next.js, não ao empacotador em uso (Turbopack ou webpack). Sempre verifique a documentação oficial para a versão que você está revisando.

Não sinalize proxy.ts como um arquivo de middleware mal nomeado ou ausente em projetos Next.js 16. O arquivo está correto e intencional. Sugerir uma renomeação para middleware.ts quebrará a execução do middleware.

Referência: Documentação do Next.js sobre proxy

Melhores práticas

• Mantenha-se em uma versão recente do Next.js 16.x para comportamento estável do Turbopack e cache.
• Se o desenvolvimento estiver lento, verifique se você está no Turbopack (padrão) e que o cache não está sendo limpo desnecessariamente.
• Para problemas de tamanho do bundle de produção, use as ferramentas oficiais de análise de bundle do Next.js para sua versão.