Capítulo 55 de 456

Memory Usage

Core Idea

Estratégias para diagnosticar e reduzir consumo de memória do Next.js em desenvolvimento e build de produção, cobrindo desde redução de dependências até flags experimentais e desabilitação de features que consomem memória.

Key Concepts

  • experimental.webpackMemoryOptimizations: (desde v15.0.0) reduz uso máximo de memória no Webpack, com leve aumento no tempo de compilação; considerado low-risk apesar de experimental.
  • next build --experimental-debug-memory-usage: (desde 14.2.0) imprime heap usage e estatísticas de garbage collection durante o build, tira heap snapshots automaticamente perto do limite configurado; incompatível com Webpack build worker.
  • --heap-prof: flag do Node.js para gravar um heap profile (node --heap-prof node_modules/next/dist/bin/next build), analisável no Chrome DevTools.
  • NODE_OPTIONS=--inspect: expõe o inspector agent do Node para conectar Chrome DevTools e tirar snapshot do heap; --inspect-brk pausa antes do código do usuário rodar.
  • SIGUSR2: sinal que, durante --experimental-debug-memory-usage, força uma heap snapshot a qualquer momento; snapshot salva na raiz do projeto.
  • Webpack build worker: roda compilações Webpack num worker Node.js separado, reduzindo memória; habilitado por padrão desde v14.1.0 se não houver config Webpack customizada (senão, experimental.webpackBuildWorker: true).
  • Webpack cache: cache em memória/disco que acelera builds mas aumenta uso de memória; pode ser desabilitado via config custom do webpack.
  • typescript.ignoreBuildErrors: pula o typechecking no build (economiza memória em projetos grandes), mas arrisca deploys com erros de tipo não detectados.
  • Source maps: productionBrowserSourceMaps: false, experimental.serverSourceMaps: false, e enablePrerenderSourceMaps: false reduzem memória consumida gerando source maps.
  • experimental.preloadEntriesOnStart: por padrão, o servidor pré-carrega os módulos JS de cada página na memória ao iniciar (resposta mais rápida, footprint inicial maior); setar false desativa isso, mas o footprint final tende a igualar se todas as páginas forem requisitadas eventualmente (módulos não são descarregados).

Code Examples

node --heap-prof node_modules/next/dist/bin/next build
  • O que demonstra: gera .heapprofile para análise de memory leak no Chrome DevTools.
// next.config.mjs — desabilitar webpack cache em produção
const nextConfig = {
  webpack: (config, { dev }) => {
    if (config.cache && !dev) {
      config.cache = Object.freeze({ type: 'memory' })
    }
    return config
  },
}
export default nextConfig
  • O que demonstra: sobrescreve o cache do webpack para reduzir footprint em build de produção.
// next.config.mjs — pular typecheck no build (arriscado)
const nextConfig = {
  typescript: {
    ignoreBuildErrors: true,
  },
}
export default nextConfig
  • O que demonstra: desativa análise estática de TypeScript durante o build para economizar memória.
// next.config.ts — desabilitar preload de entries no start
import type { NextConfig } from 'next'
const config: NextConfig = {
  experimental: {
    preloadEntriesOnStart: false,
  },
}
export default config
  • O que demonstra: reduz footprint inicial do server ao custo de latência maior na primeira request de cada página.

Anti-patterns

  • ignoreBuildErrors: true sem CI que rode typecheck separadamente: deploys podem quebrar em produção com erros de tipo não detectados.
  • Confiar só em --experimental-debug-memory-usage com Webpack build worker ativo: incompatibilidade conhecida, os dois não funcionam juntos.
  • Ignorar a atualização de versão em problema de memória no Edge runtime: v14.1.3+ já corrigiu um memory issue conhecido do Edge runtime.

Key Takeaways

  1. Primeiro passo é reduzir dependências (usar Bundle Analyzer) antes de mexer em flags experimentais.
  2. experimental.webpackMemoryOptimizations é a opção mais simples e de baixo risco para começar.
  3. Para debug profundo, combine --heap-prof ou NODE_OPTIONS=--inspect com Chrome DevTools.
  4. Desabilitar source maps e static analysis (TypeScript) economiza memória, mas com trade-offs de segurança/debug que exigem CI compensatório.
  5. preloadEntriesOnStart: false só adia o custo de memória, não o elimina definitivamente.

Connects To

  • Package Bundling / Bundle Analyzer: ferramenta para identificar dependências pesadas.
  • Development Environment: guia irmão de performance, cobre Turbopack e HMR.
  • TypeScript config (typescript.ignoreBuildErrors): referência detalhada da flag de disable de static analysis.
AnteriorMDXPróximoMigrating