junksidetm/darkside-toolkit

Next.js e Turbopack

Next.js 16+ usa Turbopack por padrão para desenvolvimento local: um bundler incremental escrito em Rust que acelera significativamente a inicialização do dev e as atualizações a quente.

Quando Usar

• Turbopack (dev padrão): Use para o desenvolvimento diário. Inicialização a frio e HMR mais rápidos, especialmente em aplicações grandes.
• Webpack (dev legado): Use apenas se encontrar um bug no Turbopack ou depender de um plugin exclusivo do webpack em dev. Desabilite 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 de build de produção (next build) pode usar Turbopack ou webpack dependendo da versão do Next.js; consulte 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 dev ou HMR, ou otimizando bundles de produção.

Como Funciona

• Turbopack: Bundler incremental para o dev do Next.js. Usa cache do sistema de arquivos para que as reinicializações sejam muito mais rápidas (ex.: 5–14x em projetos grandes).
• Padrão no dev: 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 fica tipicamente em .next; nenhuma configuração extra é necessária para uso básico.
• Bundle Analyzer (Next.js 16.1+): Bundle Analyzer 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 Bundle Analyzer (consulte a documentação do Next.js) para otimizar code-splitting e aparar dependências grandes. Prefira App Router e componentes de servidor quando possível.

Nomenclatura do Arquivo Middleware

O Next.js 16 introduziu proxy.ts como o nome do arquivo 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 a qual bundler (Turbopack ou webpack) está em uso. Verifique sempre a documentação oficial para a versão que você está revisando.

Não sinalize proxy.ts como um arquivo 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 proxy no Next.js

Boas Práticas

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