Configuration

User-facing configuration: next.config.js (or .mjs / .ts). Loaded and validated at the start of every command — next dev, next build, next start.

Loading

packages/next/src/server/config.ts (74 KB) is the loader. It:

1. Resolves next.config.{js,mjs,ts,cjs} in the project root.
2. Imports it. For .ts, uses an in-process esbuild-based loader.
3. Calls the function form ((phase, { defaultConfig }) => config) or returns the object form.
4. Merges defaults from config-shared.ts.
5. Validates against config-schema.ts.
6. Caches the result on globalThis.__NEXT_CONFIG__ so reloads share it.

Schema

Two files describe the schema:

File	What
packages/next/src/server/config-shared.ts (72 KB)	Default values + TypeScript types for every option
packages/next/src/server/config-schema.ts (27 KB)	Zod-style validation schema

Together they define the canonical set of next.config.js keys. Any change to user-facing config touches both.

Major option groups

Build / runtime

Key	What
reactStrictMode	Wrap top-level in <StrictMode>
productionBrowserSourceMaps	Emit source maps for browser bundles
output: 'standalone' | 'export'	Output mode (default = managed .next/)
distDir	Output directory (default .next)
cleanDistDir	Clear output dir before each build
generateBuildId	Function returning a stable build id
generateEtags	Emit ETags for static responses
assetPrefix	Prefix for static asset URLs
basePath	Mount the app under a subpath
trailingSlash	Add trailing / to all routes
pageExtensions	Default ['ts','tsx','js','jsx','mdx']

Routing

Key	What
redirects() / rewrites() / headers()	Async functions returning route lists
i18n	Internationalization (locales + default)

Bundler / compiler

Key	What
webpack(config, { ... })	webpack config customization
turbopack	Turbopack-specific options
compiler.styledComponents	Built-in styled-components SWC plugin
compiler.relay	Built-in Relay plugin
compiler.removeConsole	Strip console.* in production

Images

Key	What
images.deviceSizes	Width breakpoints
images.imageSizes	Smaller width set for inline images
images.formats	Optimizer output formats
images.minimumCacheTTL	Per-variant cache TTL
images.remotePatterns	Allowlist for remote sources
images.localPatterns	Allowlist for local paths
images.loader	'default' / 'cloudinary' / 'imgix' / 'custom'
images.unoptimized	Disable optimization (e.g., static export)

Experimental

Key (under experimental.*)	What
useCache	Enable 'use cache'
cacheComponents	Cache components umbrella
ppr	Partial Prerendering
dynamicIO	Dynamic IO
taint	React taint API
instrumentationHook	instrumentation.ts support
serverActions.bodySizeLimit	Action body size cap
optimizePackageImports	List of barrel files to optimize
serverComponentsHmrCache	HMR-time RSC cache

Telemetry

Key	What
telemetry.disabled	Opt out programmatically

Phases

config.ts exports phases: PHASE_DEVELOPMENT_SERVER, PHASE_PRODUCTION_BUILD, PHASE_PRODUCTION_SERVER, PHASE_TEST. The function form of next.config.js receives the phase so config can branch on it.

Adding a new option

1. Add to packages/next/src/server/config-shared.ts with a default and TS type.
2. Add validation to packages/next/src/server/config-schema.ts.
3. Consume in the relevant module (build, server, etc.).
4. If the option crosses to Rust, mirror it in crates/next-core/src/next_config.rs.
5. If it gates client code, plumb through packages/next/src/build/define-env.ts.
6. Document in docs/.
7. Test in packages/next/src/server/config.test.ts.

Loading a .ts config

The framework uses a tiny embedded esbuild instance to compile next.config.ts on the fly. This is in packages/next/src/server/config-utils.ts. The compiled JS is cached under .next/cache/.

Examples in the repo

examples/next-config-as-code/ (and others) demonstrate idioms.

Key source files

File	Purpose
packages/next/src/server/config.ts	Loader + merging
packages/next/src/server/config-shared.ts	Defaults + types
packages/next/src/server/config-schema.ts	Validation schema
packages/next/src/server/config-utils.ts	TS-config compile helper
crates/next-core/src/next_config.rs	Rust mirror