Capítulo 388 de 456

next.config.js Options

Core Idea

Página de entrada da configuração do Next.js: formato do arquivo next.config.js/.mjs/.ts, formas de definição (objeto, função, função async, por phase) e índice de todas as opções disponíveis.

Key Concepts

  • next.config.js: módulo Node.js normal na raiz do projeto, com default export; não incluído no build de browser
  • next.config.mjs: variante ESM, necessária se o projeto usa ECMAScript Modules
  • next.config.ts: variante TypeScript, tipada via NextConfig
  • Configuration as a Function: next.config pode exportar uma função (phase, { defaultConfig }) => config, inclusive async
  • Phase: contexto de carregamento da config, importável de next/constants (ex.: PHASE_DEVELOPMENT_SERVER)
  • Unit Testing (experimental): next/experimental/testing/server expõe unstable_getResponseFromNextConfig para testar headers/redirects/rewrites do config sem subir o servidor
  • .cjs/.cts: extensões não suportadas para o config

Code Examples

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 phase (dev vs. outras).
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: unit test isolado de redirects sem precisar rodar o servidor completo (mas não considera proxy/filesystem routes).

Reference Tables

Lista de opções indexadas nesta página (cada uma é um capítulo próprio quando cobre este lote): adapterPath, allowedDevOrigins, assetPrefix, basePath, bundlePagesRouterDependencies, compress, crossOrigin, deploymentId, devIndicators, distDir, env, exportPathMap, generateBuildId, generateEtags, headers, httpAgentOptions, images, logging, onDemandEntries, optimizePackageImports, output, pageExtensions, poweredByHeader, productionBrowserSourceMaps, experimental.proxyClientMaxBodySize, reactStrictMode, redirects, rewrites, serverExternalPackages, trailingSlash, transpilePackages, turbopack, turbopackChunking, typescript, urlImports, useLightningcss, useTypeScriptCli, webpack, webVitalsAttribution.

Anti-patterns

  • Usar features JS não suportadas pelo Node.js alvo: next.config.js não passa por Webpack/Babel, roda direto no Node
  • Usar .cjs/.cts: extensões não suportadas

Key Takeaways

  1. Nenhuma config é obrigatória; buscar só as opções necessárias
  2. Config como função async foi habilitada desde o Next.js 12.1.0
  3. unstable_getResponseFromNextConfig só considera o next.config.js, resultado pode divergir de produção (proxy/filesystem routes não entram)

Connects To

  • basePath (ch392), assetPrefix (ch391), distDir (ch398): opções individuais listadas nesta página
AnteriorConfigurationPróximoadapterPath