next.config.js

What next.config.js Controls

By default, Next.js works with zero configuration, but next.config.js (or next.config.mjs/.ts) lets you customize build behavior, add redirects and rewrites, configure allowed remote image domains, set custom headers, and enable experimental features ahead of their stable release.

The file exports a single configuration object (or a function returning one), which Next.js reads at build time and merges with its internal defaults. You do not need to duplicate settings you're happy leaving at their default value.

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    remotePatterns: [{ protocol: "https", hostname: "images.example.com" }],
  },
  reactStrictMode: true,
};

module.exports = nextConfig;

The JSDoc type comment gives you autocomplete for every available config option in editors that support TypeScript-aware JavaScript.

Basic Shape of the Config File

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

module.exports = nextConfig;

• The config file must export the configuration object as the module's default export.
• You can name the variable anything; only the exported value matters.
• Use next.config.mjs for ESM syntax, or next.config.ts for a typed config with recent Next.js versions.
• Changes to next.config.js require restarting the dev server to take effect.

next.config.js Options Cheat Sheet

The configuration keys used most often in real projects.

Redirects and Rewrites

Redirects and rewrites are both defined as async functions returning an array of rules. A redirect sends the browser a new URL (changing the address bar); a rewrite serves different content for a URL while keeping the original address bar URL unchanged.

// next.config.js
module.exports = {
  async redirects() {
    return [
      { source: "/old-blog/:slug", destination: "/blog/:slug", permanent: true },
    ];
  },
  async rewrites() {
    return [
      { source: "/api/legacy/:path*", destination: "https://legacy.example.com/:path*" },
    ];
  },
};

permanent: true sends a 308 status code, telling browsers and search engines the redirect is permanent.

Allowing External Image Domains

For security, next/image refuses to optimize images from domains you haven't explicitly allowed. remotePatterns (the modern replacement for the older domains array) lets you allow-list exact hostnames, protocols, and even path patterns.

• Without a matching pattern, next/image throws an error for external image URLs.
• remotePatterns supports wildcards in the hostname for subdomains.
• Local images imported directly (e.g. import logo from "./logo.png") never need this configuration.

Common Mistakes

• Forgetting to restart the dev server after editing next.config.js.
• Using the deprecated images.domains array instead of the more flexible remotePatterns.
• Confusing redirects (change the URL) with rewrites (keep the URL, change the content).
• Putting secrets directly in the env config key, which can end up bundled into client code if misused.

Key Takeaways

• next.config.js customizes framework-level behavior beyond Next.js's zero-config defaults.
• images.remotePatterns allow-lists external domains for next/image optimization.
• redirects() and rewrites() are async functions returning arrays of routing rules.
• Redirects change the browser's URL; rewrites keep the URL but serve different content.
• Config file changes require a dev server restart to take effect.