next.config.js Configuration

next.config.js (or next.config.mjs / next.config.ts) is a plain module at your project root that Next.js reads at startup to customize how the framework behaves — image domains, redirects, headers, build output, and a long list of experimental flags all live here. It exports a single configuration object, and every field is optional.

next.config.mjs — minimal shape

/** @type {import('next').NextConfig} */
const nextConfig = {
  // options go here
}

export default nextConfig

Note

Most apps need very little custom configuration. Sensible defaults cover routing, bundling, and optimization out of the box — reach for next.config.js only when you hit a specific, concrete need (an external image host, a redirect, a build-time tweak), not as a starting checklist.

Common options

Option	What it does
`images.remotePatterns`	Allow-lists external domains that `next/image` is permitted to optimize images from
`redirects()`	Async function returning permanent/temporary redirect rules (old URL → new URL)
`rewrites()`	Async function that maps an incoming path to a different destination, transparently to the browser URL
`headers()`	Attach custom HTTP response headers (security headers, caching hints) to matching paths
`env`	Expose extra build-time environment variables (rarely needed — prefer `.env` files)
`experimental`	Opt into in-progress features (e.g. `ppr`, `after`) ahead of general availability
`output`	Change the build output target, e.g. `'standalone'` for a minimal self-contained server bundle
`eslint.ignoreDuringBuilds` / `typescript.ignoreBuildErrors`	Let `next build` succeed even with lint/type errors — useful temporarily, risky long-term

A worked example

next.config.mjs

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'images.example-cdn.com',
      },
    ],
  },

  async redirects() {
    return [
      {
        source: '/old-blog/:slug',
        destination: '/blog/:slug',
        permanent: true,
      },
    ]
  },

  async rewrites() {
    return [
      {
        source: '/docs/:path*',
        destination: 'https://docs.example.com/:path*',
      },
    ]
  },

  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          { key: 'X-Frame-Options', value: 'DENY' },
        ],
      },
    ]
  },
}

export default nextConfig

Each of these — redirects, rewrites, headers — is an async function so it can, if needed, fetch its rule list from a remote source (a CMS, a feature-flag service) at build time, not just return a static array.

next.config.js/.mjs/.ts exports one configuration object read at startup.
Reach for it for concrete needs — external image domains, redirects, rewrites, headers — not proactively.
redirects(), rewrites(), and headers() are async functions returning arrays of rules.
The experimental key gates access to features still under active development.