Configuring Next.js (next.config.js)

What is next.config.js?

next.config.js (or next.config.mjs/next.config.ts) is the main configuration file for a Next.js application. It's loaded at build time and allows you to customize various behaviors.

Basic Structure

javascript

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

module.exports = nextConfig;

typescript

// next.config.ts (Next.js 15+)
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // Configuration options
};

export default nextConfig;

Most Common Options

Images

javascript

const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "images.unsplash.com",
      },
      {
        protocol: "https",
        hostname: "cdn.example.com",
        pathname: "/uploads/**",
      },
    ],
    formats: ["image/avif", "image/webp"],
    deviceSizes: [640, 750, 828, 1080, 1200, 1920],
  },
};

Redirects

javascript

const nextConfig = {
  async redirects() {
    return [
      {
        source: "/old-blog/:slug",
        destination: "/blog/:slug",
        permanent: true, // 308 status code
      },
      {
        source: "/docs",
        destination: "/documentation",
        permanent: false, // 307 status code
      },
    ];
  },
};

Rewrites

javascript

const nextConfig = {
  async rewrites() {
    return [
      {
        source: "/api/:path*",
        destination: "https://backend.example.com/api/:path*",
      },
    ];
  },
};

Headers

javascript

const nextConfig = {
  async headers() {
    return [
      {
        source: "/api/:path*",
        headers: [
          { key: "Access-Control-Allow-Origin", value: "*" },
          { key: "Access-Control-Allow-Methods", value: "GET, POST, PUT, DELETE" },
        ],
      },
      {
        source: "/(.*)",
        headers: [
          { key: "X-Frame-Options", value: "DENY" },
          { key: "X-Content-Type-Options", value: "nosniff" },
        ],
      },
    ];
  },
};

Other Important Options

javascript

const nextConfig = {
  // Base path for the entire app
  basePath: "/app",

  // Trailing slashes: /about/ vs /about
  trailingSlash: true,

  // Output mode for deployment
  output: "standalone", // For Docker deployments

  // Strict mode
  reactStrictMode: true,

  // Enable experimental features
  experimental: {
    serverActions: { bodySizeLimit: "2mb" },
    optimizePackageImports: ["lucide-react", "@heroicons/react"],
  },

  // Webpack customization
  webpack: (config, { isServer }) => {
    // Custom webpack config
    return config;
  },

  // Environment variables available at build time
  env: {
    CUSTOM_KEY: "value",
  },

  // TypeScript settings
  typescript: {
    ignoreBuildErrors: false, // Don't set to true in production!
  },

  // ESLint settings
  eslint: {
    ignoreDuringBuilds: false,
  },
};

next.config.js is where you configure images, redirects, rewrites, headers, environment variables, and deployment settings. Key options include images.remotePatterns for external images, output: "standalone" for Docker, and redirects()/rewrites() for URL management. Always use TypeScript config (next.config.ts) when possible for type safety.

Short Answer

Interview ready

Premium

A concise answer to help you respond confidently on this topic during an interview.

Finished reading?

Practice Problems

Configuring Next.js (next.config.js)

What is next.config.js?

Basic Structure

Most Common Options

Images

Redirects

Rewrites

Headers

Other Important Options

Common Patterns

Standalone Output for Docker

Internationalization

Short Answer