Next.js Configuration Guide

1. Configuration File Basics

1.1 File Types

Next.js supports two configuration file formats:

// next.config.js - CommonJS format
/** @type {import('next').NextConfig} */
const nextConfig = {
  /* config options */
}
module.exports = nextConfig

// next.config.mjs - ES Modules format
/** @type {import('next').NextConfig} */
const nextConfig = {
  /* config options */
}
export default nextConfig

1.2 Dynamic Configuration

// Function format
module.exports = (phase, { defaultConfig }) => {
  return {
    /* config options */
  }
}

// Async function format
module.exports = async (phase, { defaultConfig }) => {
  return {
    /* config options */
  }
}

2. Core Configuration Options

2.1 Routing and Rewriting

module.exports = {
  // Redirect configuration
  async redirects() {
    return [
      {
        source: '/old-path',
        destination: '/new-path',
        permanent: true,
      },
    ]
  },

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

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

2.2 Build Configuration

module.exports = {
  // Production build output directory
  distDir: 'build',

  // Build ID
  generateBuildId: async () => {
    return 'my-build-id'
  },

  // Build compression
  compress: true,

  // Static page generation config
  output: 'standalone',

  // Image optimization
  images: {
    domains: ['example.com'],
    deviceSizes: [640, 750, 828, 1080, 1200],
    imageSizes: [16, 32, 48, 64, 96],
    formats: ['image/webp'],
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
        port: '',
        pathname: '/images/**',
      },
    ],
  },
}

2.3 Development Tools

module.exports = {
  // Development server config
  devIndicators: {
    buildActivity: true,
    buildActivityPosition: 'bottom-right',
  },

  // JIT compilation
  experimental: {
    serverActions: true,
  },

  // Development error handling
  onDemandEntries: {
    maxInactiveAge: 25 * 1000,
    pagesBufferLength: 2,
  },
}

2.4 Internationalization

module.exports = {
  i18n: {
    locales: ['en', 'fr', 'de'],
    defaultLocale: 'en',
    domains: [
      {
        domain: 'example.com',
        defaultLocale: 'en',
      },
      {
        domain: 'example.fr',
        defaultLocale: 'fr',
      },
    ],
  },
}

2.5 Optimization and Caching

module.exports = {
  // Cache configuration
  onDemandEntries: {
    maxInactiveAge: 25 * 1000,
    pagesBufferLength: 2,
  },

  // Static optimization
  experimental: {
    optimizeCss: true,
    scrollRestoration: true,
  },

  // Build optimization
  swcMinify: true,
  
  // Incremental Static Regeneration
  staticPageGenerationTimeout: 60,
}

3. Common Configuration Combinations

3.1 Basic Development Config

module.exports = {
  reactStrictMode: true,
  swcMinify: true,
  compiler: {
    removeConsole: process.env.NODE_ENV === 'production',
  },
  poweredByHeader: false,
}

3.2 Production Optimization Config

module.exports = {
  compress: true,
  generateEtags: true,
  poweredByHeader: false,
  productionBrowserSourceMaps: false,
  reactStrictMode: true,
  swcMinify: true,
}

3.3 Development Environment Config

module.exports = {
  devIndicators: {
    buildActivity: true,
  },
  eslint: {
    ignoreDuringBuilds: process.env.NODE_ENV === 'production',
  },
  typescript: {
    ignoreBuildErrors: process.env.NODE_ENV === 'production',
  },
}

4. Best Practices

4.1 Environment-based Configuration

module.exports = (phase, { defaultConfig }) => {
  const isDev = phase === PHASE_DEVELOPMENT_SERVER
  return {
    ...defaultConfig,
    ...({
      // Environment-specific settings
      env: {
        customKey: isDev ? 'dev_value' : 'prod_value',
      },
    })
  }
}

4.2 Security Configuration

module.exports = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: "default-src 'self'",
          },
          {
            key: 'X-Frame-Options',
            value: 'DENY',
          },
        ],
      },
    ]
  }
}

4.3 Performance Optimization

module.exports = {
  swcMinify: true,
  experimental: {
    optimizeCss: true,
  },
  images: {
    formats: ['image/avif', 'image/webp'],
    minimumCacheTTL: 60,
  },
}

5. Important Notes

1. Configuration Validation

   • Test configurations in development
   • Use TypeScript for type hints
   • Follow official documentation

2. Performance Considerations

   • Avoid over-configuration
   • Balance features and performance
   • Test build time impacts

3. Security

   • Handle sensitive information properly
   • Configure security headers correctly
   • Update dependencies regularly

4. Maintainability

   • Keep configuration files clean
   • Add necessary comments
   • Modularize complex configurations

6. Guidelines for Usage

1. Start Simple

   • Begin with basic configuration
   • Add features as needed
   • Understand each option's purpose

2. Environment Awareness

   • Separate development and production configs
   • Use environment variables
   • Consider different deployment scenarios

3. Regular Updates

   • Monitor Next.js updates
   • Review and update configurations
   • Remove unused options

4. Documentation

   • Comment complex configurations
   • Document custom solutions
   • Maintain change history

Remember:

• Configuration changes require server restart
• Some options only work in production
• Keep up with official documentation
• Test thoroughly before deployment

Key recommendations for using the Next.js configuration:

1. Progressive Configuration

   • Start with essential options
   • Add features gradually
   • Avoid unnecessary complexity

2. Environment Management

   • Use environment variables
   • Separate development/production settings
   • Handle sensitive data properly

3. Performance Focus

   • Optimize build configurations
   • Monitor performance impacts
   • Use caching effectively

4. Security Mindset

   • Configure security headers
   • Protect API routes
   • Regular security audits

This translation provides a comprehensive overview of Next.js configuration while maintaining technical accuracy and practical usability. The structure allows for easy reference and implementation in international projects.