remotePatterns replaces the old domains array (which is now deprecated) and is significantly more secure — you can restrict not just to a hostname but to specific path patterns. The ** glob matches any subdomain.

formats: ['image/avif', 'image/webp'] enables both formats. AVIF is roughly 20% smaller than WebP for the same visual quality but takes longer to encode, which is why it's disabled by default. For a production app with an image CDN doing the optimization, enable both.

---

transpilePackages, serverExternalPackages, and Monorepo Config

transpilePackages tells Next.js to run specific npm packages through its Babel/SWC transform. You need this for two scenarios: packages in a monorepo that contain TypeScript or JSX and aren't pre-compiled, and packages distributed as ESM that Webpack can't handle natively:

serverExternalPackages is the opposite: it tells Next.js to exclude certain packages from the server bundle and use native Node.js require() instead. You need this for packages with native bindings that can't be bundled: sharp, @prisma/client, canvas, bcrypt:

Getting this wrong produces cryptic errors. If you see Module not found: Can't resolve 'fs' or similar Node.js module errors during the build, a package that needs native Node.js resolution has ended up in the bundle.

---

React Compiler and Typed Routes

Two newer config flags worth knowing about. reactCompiler: true enables the React Compiler (previously known as React Forget), which automatically memoizes your components and hooks without manual useMemo and useCallback calls. As of Next.js 15, it's stable enough for production:

The compiler's job is to analyze your code and insert memoization where it's safe. The result is fewer unnecessary re-renders without the cognitive overhead of manually auditing which values need to be memoized. If you're on React 19 (which Next.js 15 requires), the compiler is worth enabling.

typedRoutes: true gives you type-safe href props on <Link> and in router.push(). Routes are statically analyzed and a TypeScript union type is generated from your file structure:

With this enabled, <Link href="/daschboard"> (note the typo) becomes a TypeScript error. The generated types live in .next/types/link.d.ts. This is one of those features that feels like a minor convenience until it catches a broken link in code review.

---

Turbopack Configuration

Turbopack became stable in Next.js 15 for development. Enable it with --turbopack in your dev script or configure it in next.config.ts:

The rules config maps file extensions to loaders — the Turbopack equivalent of Webpack's module.rules. The syntax is different from Webpack but the concept is the same. Not all Webpack loaders are Turbopack-compatible; check the Turbopack docs for supported loaders.

---

Environment Variables Done Right

Next.js has a hierarchy of environment files: .env (committed, defaults), .env.local (gitignored, local overrides), .env.development and .env.production (environment-specific, committed), and .env.development.local / .env.production.local (gitignored, local environment-specific overrides). The loading order means local files always win.

The NEXT_PUBLIC_ prefix is the single most important convention: variables prefixed with it are inlined into the client bundle. Everything else stays server-side. This means NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY is fine to expose to the browser; STRIPE_SECRET_KEY (no prefix) stays on the server. If you ever see a secret key in a NEXT_PUBLIC_ variable, that's a security incident.

Validate your environment variables at startup with Zod rather than letting the app fail at runtime when it tries to use a missing value:

Import env from this file instead of reading process.env directly. The Zod parse throws at module load time if anything is missing or malformed — you find out immediately when the server starts, not when the first request hits the code path that uses the missing value. This has saved production deployments.

---

instrumentation.ts — Server-Side Startup Hook

instrumentation.ts at the root of your project exports a register() function that Next.js calls exactly once when the server starts. This is the correct place to initialize OpenTelemetry, set up Sentry, or wire up any APM tooling:

The NEXT_RUNTIME check is important. Next.js runs some routes in the Edge runtime and others in Node.js. OpenTelemetry's Node.js SDK doesn't work in the Edge runtime. Check the runtime before importing runtime-specific packages.

instrumentation.ts is not Middleware. It does not run on every request. It runs once, at startup. The confusion between the two is common; the mental model to use is "instrumentation is like an application constructor, middleware is like a request interceptor."

---

instrumentation-client.ts — Browser Startup Hook

instrumentation-client.ts is the client-side mirror of instrumentation.ts. It runs once in the browser when the application first loads, before any page renders:

The onRouteChange export is specific to instrumentation-client.ts — it's called by Next.js on every client-side route change, making it the right place to fire analytics page views without hooking into usePathname in every layout.

The combination of instrumentation.ts for server-side observability and instrumentation-client.ts for browser-side observability gives you full-stack coverage without spreading initialization code across layouts, providers, and components. That separation is the whole point.

---

The NEXT_PUBLIC_ Build-Time Trap

This is the most consistently misunderstood environment variable behaviour in Next.js, and it causes real production incidents when teams adopt Docker-based deployments.

The problem in one sentence: NEXT_PUBLIC_ variables are inlined into the JavaScript bundle at build time, not read from the environment at runtime.

Here's what that means in practice. You build your Docker image:

You push that image to your registry. Your CD pipeline promotes it from staging to production. Production containers start. Every API call your application makes goes to https://staging.api.example.com — because that value was baked into the bundle during the build. Setting NEXT_PUBLIC_API_URL=https://api.example.com in your production environment has no effect. The bundle doesn't read it at runtime.

This is not a bug. It's the design. NEXT_PUBLIC_ variables are statically replaced at compile time — Next.js runs a transform similar to sed -i "s/process.env.NEXT_PUBLIC_API_URL/'https:\/\/staging.api.example.com'/g" across your entire JavaScript output. The string is in the bundle. There's no process.env call at runtime.

Verifying the Problem

Patterns for Runtime-Variable Configuration

If you need different values in different environments from the same Docker image, you have three options:

Option 1: Build per environment (simplest, most common)

Build a separate image per environment. Staging gets a staging build; production gets a production build. This is the easiest approach and works fine for most teams.

The downside: you're shipping untested code to production (the staging build is what was tested; the production build is a new artifact). For most teams this is an acceptable trade-off. For highly regulated systems, it isn't.

Option 2: Route handler as a config endpoint (same image, runtime config)

Instead of NEXT_PUBLIC_API_URL in the bundle, expose a /api/config Route Handler that reads server-side environment variables and returns them. The client fetches this once at startup.

This works but adds a network round-trip on first use. Cache the result.

Option 3: publicRuntimeConfig (legacy, but still works)

publicRuntimeConfig is read at request time from the server's environment. It works for same-image promotions. The downside: it disables static rendering for all pages that use it — every page that calls getConfig() becomes server-rendered. Use it carefully.

Which Pattern to Use

The rule: if your deployment pipeline promotes the same Docker image from staging to production, NEXT_PUBLIC_ variables are the wrong tool. Use a config endpoint instead.

The CI Check

Catch accidental NEXT_PUBLIC_ usage in shared libraries that get bundled into both server and client:

Server-side code doesn't need NEXT_PUBLIC_ — server environment variables are available via process.env directly, without the build-time baking behaviour.

---