Capítulo 409 de 456

output

Core Idea

Controls Output File Tracing: during next build, Next.js traces exactly which files each page needs, letting you deploy a minimal production bundle instead of shipping full node_modules.

Key Concepts

  • output: 'standalone': generates a .next/standalone folder with only the necessary files plus a minimal server.js, deployable without npm install.
  • @vercel/nft: library Next.js uses under the hood to statically analyze import/require/fs usage.
  • .next/next-server.js.nft.json: trace file for the production server itself.
  • outputFileTracingRoot: sets the tracing root directory, needed in monorepos so files outside the app package aren't excluded.
  • outputFileTracingExcludes / outputFileTracingIncludes: objects keyed by route glob (matched with picomatch, e.g. /api/hello) whose values are glob patterns (resolved from project root) to exclude/include files from a route's trace.

Code Examples

module.exports = {
  output: 'standalone',
}

cp -r public .next/standalone/ && cp -r .next/static .next/standalone/.next/
node .next/standalone/server.js
  • O que demonstra: gera o build standalone e copia manualmente public/.next/static (não incluídos por padrão) antes de rodar o server mínimo.
module.exports = {
  outputFileTracingExcludes: {
    '/api/hello': ['./un-necessary-folder/**/*'],
  },
  outputFileTracingIncludes: {
    '/api/another': ['./necessary-folder/**/*'],
  },
}
  • O que demonstra: força exclusão/inclusão de arquivos específicos no trace de uma rota quando o tracing automático erra.

Anti-patterns

  • Usar **/* na raiz do repo em outputFileTracingIncludes: gera traces gigantes; mantenha os padrões o mais estreitos possível.
  • Esperar que server.js sirva public/.next/static sem copiar: por padrão essas pastas não são copiadas (esperado que um CDN sirva), precisa copiar manualmente se for servir via server.js.

Key Takeaways

  1. output: 'standalone' substitui a necessidade do alvo serverless deprecated e evita instalar node_modules completo em produção (ex: Docker).
  2. PORT e HOSTNAME são configuráveis via env vars ao rodar server.js.
  3. Em monorepo, outputFileTracingRoot define a raiz de tracing; combine com outputFileTracingIncludes para puxar arquivos de fora do package.
  4. Edge Runtime routes e páginas totalmente estáticas não são afetadas pelas opções de tracing.
  5. next.config.js é serializado dentro do server.js gerado durante o build.

Connects To

  • serverExternalPackages: também lida com como dependências server-side são resolvidas no bundle.
  • Self-hosting guide: contexto de deploy com Docker usando standalone output.
AnterioroptimizePackageImportsPróximopageExtensions