Next.js Config Reference

Essential configuration options for your Next.js application

⚙️ What is next.config.js?

The next.config.js file is the configuration hub for your Next.js application. It allows you to customize build behavior, add redirects, configure images, and control various framework features to match your project needs. 


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

module.exports = nextConfig

Common Configuration Options

🖼️

Image Config

Configure image optimization settings 

images: {
  domains: ['example.com'],
  formats: ['image/webp']
}
🔀

Redirects

Set up URL redirects 

async redirects() {
  return [{
    source: '/old',
    destination: '/new',
    permanent: true
  }]
}
🌍

Environment

Define environment variables 

env: {
  API_URL: 'https://api.example.com',
  SITE_NAME: 'My App'
}
📦

Base Path

Deploy to a subdirectory 

basePath: '/docs',
assetPrefix: '/docs'

🔹 Image Configuration

Configure Next.js Image component to optimize images from external sources. This setting allows you to specify which domains are allowed for image optimization and what formats to use for better performance. 

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    domains: ['cdn.example.com', 'images.unsplash.com'],
    formats: ['image/avif', 'image/webp'],
    deviceSizes: [640, 750, 828, 1080, 1200],
    imageSizes: [16, 32, 48, 64, 96],
  },
}

module.exports = nextConfig

Result:

✅ Images from specified domains will be optimized

✅ AVIF and WebP formats enabled for better compression

✅ Responsive image sizes configured

🔹 Redirects and Rewrites

Set up URL redirects to move users from old URLs to new ones, or use rewrites to proxy requests to external APIs. Redirects change the browser URL while rewrites keep the original URL visible to users. 

/** @type {import('next').NextConfig} */
const nextConfig = {
  async redirects() {
    return [
      {
        source: '/old-blog/:slug',
        destination: '/blog/:slug',
        permanent: true, // 301 redirect
      },
      {
        source: '/temp',
        destination: '/new-page',
        permanent: false, // 302 redirect
      },
    ]
  },
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: 'https://api.example.com/:path*',
      },
    ]
  },
}

module.exports = nextConfig

Result:

✅ /old-blog/hello → redirects to /blog/hello (permanent)

✅ /temp → redirects to /new-page (temporary)

✅ /api/users → proxies to https://api.example.com/users

🔹 Environment Variables

Define environment variables directly in your config file for quick access throughout your application. These variables are available at build time and can be used in both server and client code when prefixed with NEXT_PUBLIC_. 

/** @type {import('next').NextConfig} */
const nextConfig = {
  env: {
    API_URL: process.env.API_URL || 'https://api.example.com',
    NEXT_PUBLIC_SITE_NAME: 'My Awesome App',
    NEXT_PUBLIC_VERSION: '1.0.0',
  },
}

module.exports = nextConfig

// Usage in your components:
// const apiUrl = process.env.API_URL
// const siteName = process.env.NEXT_PUBLIC_SITE_NAME

Result:

✅ Variables available via process.env

✅ NEXT_PUBLIC_ prefix makes variables available in browser

✅ Fallback values provided for missing env vars

🔹 Custom Webpack Configuration

Extend the default webpack configuration to add custom loaders, plugins, or modify build behavior. This is useful when you need to integrate special file types or optimize your bundle in specific ways. 

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    // Add custom webpack rules
    config.module.rules.push({
      test: /\.svg$/,
      use: ['@svgr/webpack'],
    })

    // Modify config based on server/client
    if (!isServer) {
      config.resolve.fallback = {
        fs: false,
        net: false,
        tls: false,
      }
    }

    return config
  },
}

module.exports = nextConfig

Result:

✅ SVG files can be imported as React components

✅ Node.js modules excluded from client bundle

✅ Custom webpack configuration applied

🔹 Output and Deployment Options

Configure how Next.js builds and exports your application for different deployment scenarios. Choose between standalone output for Docker containers or static export for hosting on CDNs without a Node.js server. 

/** @type {import('next').NextConfig} */
const nextConfig = {
  // For Docker/standalone deployment
  output: 'standalone',
  
  // For static site generation
  // output: 'export',
  
  // Disable x-powered-by header
  poweredByHeader: false,
  
  // Compression
  compress: true,
  
  // Trailing slash behavior
  trailingSlash: false,
}

module.exports = nextConfig

Result:

✅ Standalone build includes minimal Node.js runtime

✅ Security headers configured

✅ Gzip compression enabled

🔹 Complete Configuration Example

Here's a comprehensive next.config.js file combining multiple configuration options for a production-ready application with image optimization, redirects, environment variables, and custom webpack settings. 

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  swcMinify: true,
  
  images: {
    domains: ['cdn.example.com'],
    formats: ['image/avif', 'image/webp'],
  },
  
  async redirects() {
    return [
      {
        source: '/home',
        destination: '/',
        permanent: true,
      },
    ]
  },
  
  env: {
    NEXT_PUBLIC_API_URL: process.env.API_URL,
  },
  
  webpack: (config) => {
    config.module.rules.push({
      test: /\.svg$/,
      use: ['@svgr/webpack'],
    })
    return config
  },
}

module.exports = nextConfig

Result:

✅ Production-ready configuration

✅ Optimized images and fast builds

✅ Custom redirects and environment variables

✅ SVG support enabled

🧠 Test Your Knowledge

What is the purpose of next.config.js?