next.config.ts — Wrong images.remotePatterns Blocked All External Images in Production

next.config.ts (or next.config.js for the JavaScript SDK) is the single configuration file that controls every aspect of Next.js behaviour — from how images are optimised to how routes are rewritten to how the React compiler optimises your components. With 50+ configurable options spanning 10 categories, it is simultaneously the most powerful and most misunderstood file in a Next.js project.

The most common production issue: images.remotePatterns configured incorrectly. A single missing field, wrong wildcard placement, or omitted protocol causes every external image in your application to return a 404 or fall back to the unoptimized original URL — silently, with no build errors or runtime warnings. This issue is the #1 support complaint across Next.js projects.

This article covers every meaningful option in next.config.ts: images (the most error-prone), routing (redirects, rewrites, headers, middleware config), build tooling (webpack, turbopack, bundle analysis), server configuration (serverActions, output, experimental features), React configuration (reactCompiler, strictMode), and environment variable handling. For each option, you get the production-ready configuration and the mistakes to avoid.

By the end, you will be able to read any next.config.ts and understand exactly what every line does — and more importantly, which lines are likely to cause production incidents.

images.remotePatterns — The #1 Configuration Footgun

The images config block controls how Next.js optimises images — resizing, format conversion (WebP/AVIF), quality, and caching. It is the most frequently misconfigured option in production. The remotePatterns array defines which external image hosts are allowed for optimisation.

Each remotePattern entry requires three fields: protocol ('http' or 'https'), hostname (exact domain or wildcard pattern), and optionally port and pathname. All fields are validated at request time when the /_next/image endpoint processes an image. If any field does not match, the image request returns 404.

The wildcard syntax: matches this and all subdomains. .example.com matches example.com, cdn.example.com, a.b.example.com. *.example.com (single asterisk) matches only one level — cdn.example.com but NOT a.b.example.com. Single asterisk is often used accidentally and causes intermittent failures.

The production pattern: explicitly list every domain that serves images. Prefer exact hostnames over wildcards where possible. Always specify both protocol and hostname. Add a CI check that validates every remotePattern entry against a whitelist of expected domains — if a domain is missing from the config but appears in the content, the CI should warn.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  images: {
    // REQUIRED for remote images with next/image
    // Each entry must have BOTH protocol AND hostname
    remotePatterns: [
      {
        protocol: 'https',
        // Exact match:
        hostname: 'cdn.example.com',
      },
      {
        protocol: 'https',
        // Wildcard: ** matches any subdomain (including none)
        hostname: '**.example.com',
      },
      {
        protocol: 'https',
        hostname: 'images.unsplash.com',
      },
      // Optional: restrict path and port
      {
        protocol: 'https',
        hostname: 'media.example.com',
        port: '443',
        pathname: '/uploads/**',
      },
    ],

    // Image optimisation settings
    formats: ['image/avif', 'image/webp'],
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
    minimumCacheTTL: 60 * 60 * 24, // 24 hours

    // Danger zone: disables image optimisation
    // unoptimized: true, // Only for static export
  },
}

export default nextConfig

Redirects, Rewrites, and Headers — Async Functions, Not Objects

A common mistake: defining redirects, rewrites, or headers as static arrays instead of async functions. Next.js expects these to be async functions that return an array — because in some configurations, you need to fetch external data (like feature flags) to determine the routing config.

The syntax: async redirects() { return [ / array of rules / ] }. Each rule has source (incoming URL pattern), destination (target URL), and permanent (true = 301, false = 307) for redirects. headers similarly returns an array of { source, headers: [{ key, value }] } objects.

Path patterns: use :param for named parameters, for zero-or-more wildcard, :path for catch-all segments. The pattern /blog/:slug matches /blog/hello-world with slug = 'hello-world'. The pattern /api/:path* matches /api/v1/users with path = 'v1/users'.

Performance implication: redirects and headers are evaluated on every request. Having 100+ redirect rules can add 10-50ms per request on cold start. For large redirect sets, consider a middleware-based approach or a CDN-level redirect (Vercel Edge Config, Cloudflare Bulk Redirects) instead.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  async redirects() {
    return [
      {
        source: '/old-blog/:slug',
        destination: '/blog/:slug',
        permanent: true, // 301 — SEO-friendly
      },
      {
        source: '/products/:id',
        has: [
          {
            type: 'cookie',
            key: 'vip',
            value: 'true',
          },
        ],
        destination: '/vip/products/:id',
        permanent: false, // 307 — temporary
      },
    ]
  },

  async rewrites() {
    return [
      // Proxy external API through Next.js
      {
        source: '/api/external/:path*',
        destination: 'https://external-api.com/:path*',
      },
    ]
  },

  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          { key: 'X-Frame-Options', value: 'DENY' },
          { key: 'X-Content-Type-Options', value: 'nosniff' },
          { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
        ],
      },
      {
        source: '/_next/static/:path*',
        headers: [
          { key: 'Cache-Control', value: 'public, max-age=31536000, immutable' },
        ],
      },
    ]
  },
}

export default nextConfig

webpack and transpilePackages — When Dependencies Break the Build

Next.js abstracts Webpack configuration behind its own build pipeline. Most of the time, you don't touch Webpack directly. When you do — to add custom loaders, modify resolve aliases, or adjust SplitChunks — you must use the webpack config function.

The webpack function receives the default config and the build context ({ isServer, webpack, nextRuntime }). You modify the config and return it. Common customisations: adding SVG loaders (SVGR), configuring module aliases, adding bundle analysis plugins, and modifying resolve fallbacks for Node.js modules in browser context.

transpilePackages is a simpler alternative to custom webpack config for one specific use case: transpiling external npm packages that are not ESM-compatible. Some packages distribute only as CommonJS or untranspiled TypeScript. Adding them to transpilePackages tells Next.js to run them through the Babel/SWC pipeline, making them compatible with the browser build.

The production insight: every custom webpack configuration increases the risk of build failures when Next.js updates. The Webpack API is considered internal — Vercel changes it between major versions without deprecation warnings. Minimise custom webpack config and prefer Next.js-native solutions (transpilePackages, next/dynamic, next/image) whenever possible.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  // Transpile specific packages to ESM
  transpilePackages: [
    '@acme/ui',
    'some-esm-incompatible-lib',
  ],

  webpack: (config, { isServer, webpack }) => {
    // SVG loader example
    config.module.rules.push({
      test: /\.svg$/,
      use: ['@svgr/webpack'],
    })

    // Module aliases
    config.resolve.alias = {
      ...config.resolve.alias,
      '@': __dirname + '/src',
    }

    // Bundle analysis (run with ANALYZE=true)
    if (process.env.ANALYZE === 'true') {
      const { BundleAnalyzerPlugin } =
        require('webpack-bundle-analyzer')
      config.plugins.push(
        new BundleAnalyzerPlugin({
          analyzerMode: 'static',
          reportFilename: isServer
            ? '../analyze/server.html'
            : './analyze/client.html',
        })
      )
    }

    return config
  },

  // Custom server component module rules
  serverComponentsExternalPackages: [
    'mongoose',
    'prisma',
    'typeorm',
  ],
}

export default nextConfig

output — Static Export vs Server vs Standalone

The output option determines how Next.js builds your application. The default (no output specified) builds for a Node.js server with all Next.js features — API routes, ISR, middleware, draft mode, server actions. The output includes .next/ with server-side code that next start runs.

output: 'export' — static HTML export. Builds every page as static HTML/CSS/JS files. Output goes to out/ directory. Tradeoffs: zero server runtime (fastest, cheapest to host), NO API routes, NO ISR (all pages built at deploy time), NO middleware, NO draft mode, NO server actions. Images must be unoptimized. Suitable for: marketing sites, documentation, blogs where every page is pre-built.

output: 'standalone' — builds a self-contained deployment with minimal dependencies. Output includes a standalone/ directory with the server code and a minimal node_modules. Tradeoffs: larger output (includes server runtime), enables all Next.js features. Requires a Node.js runtime. Suitable for: Docker deployments, self-hosted production, any app that needs ISR or API routes.

The mistake: teams choose output: 'export' for performance, then discover they need ISR or API routes and must migrate — a significant effort. Choose output based on your feature requirements, not perceived performance.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  // Option 1: Static export (no server needed)
  // Output goes to `out/` directory
  // Caveats: no API routes, no ISR, no middleware, no draft mode
  // output: 'export',

  // Option 2: Self-hosted server (Docker, Node.js)
  // Output goes to `.next/standalone/`
  // Includes minimal node_modules — deploy to any Node.js host
  // output: 'standalone',

  // Option 3: Default — Vercel or full Node.js deployment
  // No output option needed
  // All features enabled

  // For static export, images must be unoptimized
  // images: { unoptimized: true },
}

export default nextConfig

serverActions — The Origin Check That Blocks Cross-Domain Requests

Server Actions in Next.js 16 include a security feature: they check the Origin header of incoming requests against an allowed list. If your app is accessed from multiple domains — for example, www.example.com and staging.example.com, or if you use a reverse proxy that changes the origin — Server Actions will return 403 Forbidden for requests from unlisted origins.

The configuration is serverActions.allowedOrigins: string[]. Each entry should be the origin (protocol + hostname, no path). The check applies to all Server Action calls, including those from client components and forms.

The production issue: teams deploy to a staging subdomain, test Server Actions, and get 403 errors. The staging domain is not in the allowed origins list. The fix is adding both the production and staging domains to the config. For local development, http://localhost:3000 must also be in the list.

Security consideration: the origin check prevents CSRF-style attacks where a malicious site tricks a user's browser into calling your Server Action. Only add trusted origins to the allowed list. Use environment variables to differentiate origins per environment.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  serverActions: {
    // REQUIRED for Server Actions called from different domains
    // Without this, cross-origin Server Action calls return 403
    allowedOrigins: [
      'https://www.example.com',
      'https://example.com',
      process.env.VERCEL_URL && `https://${process.env.VERCEL_URL}`,
      process.env.STAGING_URL,
      'http://localhost:3000',
    ].filter(Boolean) as string[],

    // Optional: body size limit for Server Actions
    // Default: 1MB — increase for file uploads via Server Actions
    bodySizeLimit: '2mb',
  },
}

export default nextConfig

experimental — Where Future Features Live (and Break)

The experimental config block contains features that are not yet stable. Using experimental features gives you access to cutting-edge capabilities but comes with risks: the API may change without notice, the feature may be removed, or it may have bugs that affect production.

Key experimental features in Next.js 16: mdxRs (Rust-based MDX compiler — faster builds but different output), turbo (enable Turbopack in development — default since 15.3), serverActions (now stable in 16, moved from experimental), reactCompiler (automatic memoization with React Forget), ppr (Partial Prerendering — experimental), optimizePackageImports (automatic tree shaking of barrel files from specific packages).

The discipline: pin the exact Next.js version when using experimental features. Never use latest in your package.json. Add a comment explaining why each experimental flag is enabled, what it does, and what the migration path is when it becomes stable. Audit experimental flags every quarter and remove those that have graduated to stable.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    // Rust-based MDX compiler — 5-10x faster MDX compilation
    // Graduated from experimental in some Next.js 16 releases
    mdxRs: true,

    // React Compiler (React Forget) — automatic memoization
    // Automatically adds useMemo/useCallback calls
    // Build time impact: ~5% longer
    reactCompiler: true,

    // Partial Prerendering - static shell + dynamic holes
    // Combines static generation with streaming SSR
    ppr: true,

    // Optimise imports from specific packages
    // Automatically treeshakes barrel files
    optimizePackageImports: [
      'lucide-react',
      '@radix-ui/react-icons',
      '@mui/material',
    ],

    // Scroll restoration options
    scrollRestoration: true,
  },
}

export default nextConfig

reactCompiler — Automatic Memoization Without useMemo

The React Compiler (formerly React Forget) is a build-time tool that automatically adds useMemo and useCallback calls to your components. It analyses component renders and determines which values need memoization to prevent unnecessary re-renders. Enabled via experimental.reactCompiler: true.

The impact: for a typical app with 50+ components, the compiler can eliminate 80-90% of manual memoization code. Components that re-render unnecessarily due to missing useMemo or inline function references are automatically optimised. The developer no longer needs to think about React.memo, useMemo, or useCallback — the compiler handles it.

The tradeoff: build time increases by approximately 5% (more for large component trees). The compiler's output is conservative — it may add memoization that is unnecessary, slightly increasing the generated bundle. Runtime behaviour is identical — the compiler only adds memoization that preserves existing semantics.

The production consideration: enable the compiler on a route-by-route basis if needed via the compilationMode option. For existing apps, enable it in a staging environment first and use React DevTools Profiler to verify that unnecessary re-renders are eliminated without breaking component behaviour.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    reactCompiler: {
      // Compilation mode:
      // 'all' — compile all components (default)
      // 'strict' — compile all, but error on patterns the
      //   compiler cannot safely optimise
      compilationMode: 'all',

      // Optional: suppress specific diagnostics
      // panicThreshold: 'error',
    },
    // Alternative: boolean shorthand
    // reactCompiler: true,
  },
}

export default nextConfig

Turbopack Configuration — Matching the Rust Bundler to Your Needs

Turbopack is the default development bundler in Next.js 16. It replaces Webpack for next dev with a Rust-based implementation that is approximately 10x faster for cold starts and substantially faster for Hot Module Replacement (HMR). The configuration is minimal because Turbopack aims to work out of the box.

The turbo config block in experimental lets you customise Turbopack-specific settings: resolve aliases, load rules for specific file types, and webpack loader compatibility. Most projects don't need this — the default Turbopack config handles TypeScript, JSX, CSS, CSS Modules, and static assets.

Key limitation: Turbopack does not support custom webpack loaders. If you use SVGR for SVG imports, custom CSS post-processors, or GraphQL codegen imports, those features won't work with Turbopack. You must either: (1) disable Turbopack and use Webpack (--no-turbo flag), (2) convert the loader to a Turbopack-compatible transform, or (3) pre-process those files outside the bundler.

The production decision: use Turbopack for development (default, faster iteration). Use Webpack for production builds (more mature optimisation, custom loader support). Do not enable Turbopack for production builds unless you have verified identical output.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    turbo: {
      // Resolve aliases (equivalent to webpack resolve.alias)
      resolveAlias: {
        '@': './src',
        '@components': './src/components',
      },

      // Load rules for specific file extensions
      rules: {
        '*.svg': {
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
      },

      // Tree shaking options
      treeShaking: true,
    },
  },

  // Force Webpack for production builds
  // webpack: (config) => { ... return config },
}

export default nextConfig

Environment Variables — Public vs Private and the NEXT_PUBLIC_ Prefix

Next.js handles environment variables through .env files (.env.local, .env.production, .env.development) and the env config option in next.config.ts. The critical distinction: which variables are available on the server vs the client.

Variables without the NEXT_PUBLIC_ prefix are server-only. They are available in getServerSideProps, API routes, Server Components, middleware, and next.config.ts itself — but NOT in client-side JavaScript. If you reference process.env.API_SECRET in a client component, it will be undefined at runtime (and replaced with the literal string at build time, potentially leaking the value if used in a string).

Variables prefixed with NEXT_PUBLIC_ are inlined at build time and available in client-side code. They are replaced with their actual values during the build — meaning any change to a NEXT_PUBLIC_ variable requires a rebuild to take effect. Use NEXT_PUBLIC_ for values that are safe to expose to the browser: API base URLs, feature flag names, public keys.

The env option in next.config.ts adds variables that are available in both server and browser contexts — essentially treating them as if they had the NEXT_PUBLIC_ prefix. Use this sparingly — it's better to be explicit with prefixes.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  // Variables available to both server and client
  // Equivalent to NEXT_PUBLIC_ prefix
  env: {
    SITE_NAME: 'TheCodeForge',
    API_BASE_URL: process.env.API_BASE_URL,
  },

  // Server-only variables (defined in .env.local, .env.production)
  // process.env.DATABASE_URL — only in server components, API routes
  // process.env.API_SECRET — never exposed to browser

  // Public variables (NEXT_PUBLIC_ prefix)
  // NEXT_PUBLIC_GA_ID — inlined at build time, available in browser

  // Stale while revalidate config
  // httpAgentOptions: {
  //   keepAlive: true,
  // },
}

export default nextConfig

// .env.local (never committed):
// DATABASE_URL=postgres://...
// API_SECRET=sk-...
// NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

Full Production Config — Putting It All Together

The production-grade next.config.ts combines all the patterns covered above into a single, well-documented configuration file. Every option is explained with a comment. Experimental features are gated by environment variables. Image remotePatterns are validated. Security headers are set. Environment-specific overrides are handled.

The key principle: the configuration should be self-documenting. Anyone on the team should be able to read the file and understand what every option does and why it's set. Use TypeScript for type safety — import type { NextConfig } from 'next' gives you autocomplete and validation.

Version control the configuration file in every environment. The file should be identical across development, staging, and production — differences should be controlled by environment variables, not by having different config files. Use .env.local for local overrides.

import type { NextConfig } from 'next'
import createMDX from '@next/mdx'

const nextConfig: NextConfig = {
  // --- Images ---
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: 'cdn.example.com' },
      { protocol: 'https', hostname: '**.vercel-storage.com' },
    ],
    formats: ['image/avif', 'image/webp'],
    minimumCacheTTL: 86400,
  },

  // --- Routing ---
  async redirects() {
    return [
      { source: '/old/:path*', destination: '/new/:path*', permanent: true },
    ]
  },
  async rewrites() {
    return [
      { source: '/api/external/:path*', destination: 'https://api.example.com/:path*' },
    ]
  },
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          { key: 'X-Frame-Options', value: 'DENY' },
          { key: 'X-Content-Type-Options', value: 'nosniff' },
          { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
          { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
        ],
      },
    ]
  },

  // --- Build & Bundler ---
  transpilePackages: ['@acme/ui', 'three'],
  experimental: {
    // Enable only if using MDX
    mdxRs: true,
    // Auto-memoization (React Forget)
    reactCompiler: process.env.ENABLE_REACT_COMPILER === 'true',
    // Optimise barrel file imports
    optimizePackageImports: ['lucide-react', '@radix-ui/react-icons'],
  },

  // --- Server ---
  serverActions: {
    allowedOrigins: [
      'https://example.com',
      process.env.VERCEL_URL && `https://${process.env.VERCEL_URL}`,
      'http://localhost:3000',
    ].filter(Boolean) as string[],
  },

  // --- Other ---
  productionBrowserSourceMaps: false,
  reactStrictMode: true,
  poweredByHeader: false,
}

const withMDX = createMDX({
  options: {
    remarkPlugins: [],
    rehypePlugins: [],
  },
})

export default withMDX(nextConfig)