Development Environment

Core Idea

Guia de diagnóstico e otimização de performance do next dev (compilação sob demanda, diferente de next build/next start), cobrindo antivírus, bundler, imports, Tailwind, webpack custom, memória, HMR de Server Components e Docker.

Key Concepts

• next dev vs produção: dev compila rotas sob demanda ao navegar; build de produção faz minificação e content hashing, ausentes em dev.
• Turbopack: bundler padrão do next dev desde as versões recentes; usar --webpack para reverter ao webpack.
• Barrel files: arquivos que reexportam muitos módulos, forçam o compiler a parsear tudo em busca de side-effects, tornando o build lento.
• optimizePackageImports: opção experimental em next.config.js que otimiza imports de pacotes que usam barrel files (Turbopack já faz isso automaticamente, sem precisar da config).
• serverComponentsHmrCache: opção experimental que cacheia respostas de fetch em Server Components entre refreshes de HMR, evitando refetch a cada mudança local.
• Docker no Mac/Windows: acesso a filesystem fora de Linux é lento, causando HMR de segundos/minutos; recomenda-se dev local e Docker só para produção/testes de build.
• logging.fetches: opção de log detalhado de requisições fetch durante o dev.
• Turbopack tracing: gera trace-turbopack.bin via --internal-trace, interpretado com npx next internal trace e visualizado em trace.nextjs.org.

Code Examples

# Atualizar e usar Turbopack (padrão)
pnpm add next@latest
pnpm dev  # Turbopack é usado por padrão

# Reverter para Webpack
pnpm dev --webpack

• O que demonstra: como alternar entre Turbopack (default) e Webpack no dev server.

// Import otimizado de ícones (evitar milhares de módulos)
// Em vez de:
import { TriangleIcon } from '@phosphor-icons/react'
// Fazer:
import { TriangleIcon } from '@phosphor-icons/react/dist/csr/Triangle'

• O que demonstra: import direto do ícone específico evita carregar toda a lib.

// next.config.js — otimizar barrel files (não necessário no Turbopack)
module.exports = {
  experimental: {
    optimizePackageImports: ['package-name'],
  },
}

• O que demonstra: configuração de otimização de imports para pacotes com barrel files, sob Webpack.

// tailwind.config.js — escopo específico do content
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}', // Good
    // '../../packages/**/*.{js,ts,jsx,tsx}', // Muito amplo, casa node_modules
  ],
}

• O que demonstra: escopo de content do Tailwind restrito evita scanning de diretórios enormes (ex: node_modules).

# Turbopack tracing
pnpm dev --internal-trace
npx next internal trace .next-profiles/trace-turbopack.bin

• O que demonstra: geração e leitura de trace de performance do Turbopack.

Anti-patterns

• Importar biblioteca de ícones inteira: @material-ui/icons, react-icons, @phosphor-icons/react sem import específico carregam milhares de módulos desnecessários.
• Misturar múltiplos sets de ícones do react-icons (pi, md, tb, cg): multiplica módulos processados pelo compiler mesmo usando um ícone de cada.
• content do Tailwind muito amplo: incluir node_modules ou diretórios grandes no glob de scanning derruba a performance do build.
• Docker para desenvolvimento no Mac/Windows: filesystem access lento causa HMR de segundos a minutos; reservar Docker para produção.
• Webpack customizado sem necessidade em dev: settings custom podem ser desnecessários localmente, considerar Turbopack ou aplicar customizações só no build de produção.

Key Takeaways

1. Adicionar a pasta do projeto à exclusão do antivírus (Windows Defender) ou habilitar Gatekeeper developer mode (macOS) reduz lentidão de acesso a arquivos.
2. Atualizar Next.js para a versão mais recente e usar Turbopack (default) traz ganhos de performance de compilação.
3. Evitar barrel files e imports amplos de ícones/pacotes; usar optimizePackageImports quando estiver em Webpack.
4. Configurar content do Tailwind com escopo específico evita scanning excessivo.
5. Preferir dev local a Docker em Mac/Windows; usar serverComponentsHmrCache para cachear fetch entre HMR refreshes.

Connects To

• Memory Usage: próximo guia, cobre otimização de memória para apps grandes.
• Package Bundling: aprofunda otimização de imports e bundling mencionada aqui.
• Turbopack config (next.config.js): referência para configurar loaders no Turbopack em vez de webpack custom.