Next.js Configuration File

Every Next.js project has a control panel in its root folder. The file next.config.js tells the framework how to build, serve, and secure your application. A fresh project ships with an almost empty version of this file. Most real projects grow it over time as needs appear.

The Everyday View

Think of a car dashboard. The car runs without you touching anything, but switches and dials let you adjust the lights, the wipers, and the climate. The configuration file plays the same role. The app runs with defaults, and the file lets you change specific behaviors.

File Names and Formats

Next.js accepts several file names. Pick one format and keep it consistent.

File Name	Module Style
next.config.js	CommonJS
next.config.mjs	ES Modules
next.config.ts	TypeScript (newer versions)

A Minimal File

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
};

module.exports = nextConfig;

The comment above the object gives code editors type hints. Autocomplete then suggests valid option names while you type.

How the File Fits In

+---------------------+
|  next.config.js     |
+---------------------+
          |
          v
+---------------------+     +----------------+
|  Build step         | --> |  .next folder  |
+---------------------+     +----------------+
          |
          v
+---------------------+
|  Running server     |
+---------------------+

Next.js reads the file when the dev server starts or when a build begins. The settings then shape every later step.

Popular Options

reactStrictMode

This option runs extra checks during development. React renders some components twice and warns about unsafe patterns. The extra work happens only in development and never reaches visitors.

images

The Image component refuses to load pictures from unknown websites. The remotePatterns setting lists allowed sources.

const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'images.example.com',
      },
    ],
  },
};

redirects and rewrites

Both options accept async functions that return rule lists. They handle moved pages and friendly URLs without extra code.

headers

The headers function attaches custom response headers to matching paths. Security-focused headers often live here.

const nextConfig = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          { key: 'X-Content-Type-Options', value: 'nosniff' },
          { key: 'X-Frame-Options', value: 'SAMEORIGIN' },
        ],
      },
    ];
  },
};

basePath

A site that lives under a sub-folder, such as /docs, needs a base path. Every route and asset URL then starts with that prefix.

const nextConfig = {
  basePath: '/docs',
};

output

The output option controls the build format. The value 'standalone' produces a small self-contained server folder that suits Docker images. The value 'export' produces plain static files for hosting on any basic web server.

const nextConfig = {
  output: 'standalone',
};

Combining Several Options

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: 'images.example.com' },
    ],
  },
  async redirects() {
    return [
      { source: '/old', destination: '/new', permanent: true },
    ];
  },
};

module.exports = nextConfig;

Using Environment Values Inside the File

The file runs in Node.js, so it can read process.env values. This trick helps when an option changes between local work and production.

const isProd = process.env.NODE_ENV === 'production';

const nextConfig = {
  reactStrictMode: !isProd,
};

Keep secrets out of this file. Anything inside the config object can leak into the build output under certain options.

Restart After Changes

Next.js reads the file only at startup. Stop the dev server with Ctrl + C and run npm run dev again after every edit. A forgotten restart explains many "my setting does nothing" moments.

Common Mistakes

Mixing Module Styles

A file named next.config.js that uses export default fails in many setups. Match the syntax to the file name.

Typing Option Names From Memory

A typo in an option name produces no obvious error. The setting simply does nothing. The type comment above the config object catches most mistakes.

Adding Options Without a Reason

Each option adds behavior that someone must maintain later. Add a setting only when a real need appears.

Quick Summary

The configuration file sits at the project root and shapes builds, images, headers, redirects, and output format. Start small, add options as needs grow, and restart the server after each change.