Capítulo 194 de 456

next.config.js

Core Idea

Central configuration file for a Next.js project, loaded by the Next.js server and build phases (not included in the browser bundle). Supports plain object, function, or async function exports, and can target specific build phases.

Key Concepts

  • next.config.js/mjs/ts: Módulo Node.js padrão; .cjs/.cts não são suportados. .mjs para ESM, .ts para TypeScript.
  • Config as function: (phase, { defaultConfig }) => nextConfig, permitindo lógica condicional por fase (inclusive async).
  • phase: Contexto de carregamento (ex. PHASE_DEVELOPMENT_SERVER), importável de next/constants.
  • unstable_getResponseFromNextConfig: Utilitário de teste unitário (desde 15.1, em next/experimental/testing/server) que executa headers, redirects e rewrites do config isoladamente.

Code Examples

// @ts-check
const { PHASE_DEVELOPMENT_SERVER } = require('next/constants')

module.exports = (phase, { defaultConfig }) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return { /* development only config options here */ }
  }
  return { /* config options for all phases except development here */ }
}
  • O que demonstra: Config condicional por fase, aplicando opções diferentes só em desenvolvimento.
import { getRedirectUrl, unstable_getResponseFromNextConfig } from 'next/experimental/testing/server'

const response = await unstable_getResponseFromNextConfig({
  url: 'https://nextjs.org/test',
  nextConfig: {
    async redirects() {
      return [{ source: '/test', destination: '/test2', permanent: false }]
    },
  },
})
expect(response.status).toEqual(307)
expect(getRedirectUrl(response)).toEqual('https://nextjs.org/test2')
  • O que demonstra: Teste unitário de uma regra de redirects sem subir o servidor completo.

Anti-patterns

  • Usar features JS não suportadas pelo Node.js alvo: next.config.js não passa por Webpack/Babel, então não é transpilado.
  • Confiar no resultado de unstable_getResponseFromNextConfig como produção-fiel: ele só considera next.config.js, ignorando rotas de proxy e filesystem — o resultado real pode diferir.

Key Takeaways

  1. Nenhuma configuração é obrigatória; procure só as opções que precisa habilitar.
  2. next.config.ts é suportado nativamente para tipagem.
  3. Configuração como função assíncrona é suportada desde 12.1.0.
  4. A página lista dezenas de opções individuais (adapterPath, basePath, images, cacheComponents, etc.) — cada uma documentada em sua própria página de referência.

Connects To

  • headers / redirects / rewrites (next.config.js): as três funções testáveis via unstable_getResponseFromNextConfig.
  • basePath, images, cacheComponents e demais opções: subpáginas individuais listadas neste índice.
AnteriorConfigurationPróximoadapterPath