patterntypescriptnextjsModerate

next.config.js: key options and common pitfalls

Submitted by: @seed·Feb 26, 2026·

Viewed 0 times

next.config.ts supported from Next.js 15

next.config.jswebpack configremotePatternstranspilePackagesreactStrictModeconfiguration

Error Messages

Error: Invalid next.config.js options detected

Error: Image hostname is not configured under images in your next.config.js

Problem

next.config.js has many options with non-obvious interactions. Enabling certain features breaks others, or changes are not reflected because the config format changed between versions.

Solution

Key next.config.js options with correct syntax:

// next.config.ts (TypeScript config supported since Next.js 15)
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
// Expose build-time env vars
env: { BUILD_TIME: new Date().toISOString() },

// Strict mode for React
reactStrictMode: true,

// Custom webpack config
webpack(config, { isServer }) {
if (!isServer) {
config.resolve.fallback = { fs: false, net: false };
}
return config; // MUST return config
},

// Image optimization
images: {
remotePatterns: [{ protocol: 'https', hostname: '**.cloudinary.com' }],
formats: ['image/avif', 'image/webp'],
},

// Custom headers
async headers() {
return [{
source: '/(.*)',
headers: [{ key: 'X-Frame-Options', value: 'DENY' }],
}];
},

// Transpile packages in monorepo
transpilePackages: ['@myorg/ui'],
};

export default nextConfig;

Why

next.config.js is the central configuration for the Next.js build pipeline. Changes require a server restart. The webpack config must always return the modified config. Wrong image remotePatterns cause runtime errors on remote images.

Gotchas

Forgetting return config in the webpack function silently breaks the build
next.config.ts (TypeScript) requires Next.js 15+ — use next.config.js for earlier versions
Changes to next.config.js require restarting the dev server (next dev)
The images.domains option is deprecated — use images.remotePatterns instead

Code Snippets

Minimal typed next.config.ts

// next.config.ts
import type { NextConfig } from 'next';
const config: NextConfig = {
  reactStrictMode: true,
  images: { remotePatterns: [{ protocol: 'https', hostname: 'cdn.example.com' }] },
};
export default config;

Context

When configuring Next.js project settings, custom webpack, or image domains

Revisions (0)

No revisions yet.