Next.js 16 vs 15: 7 breaking changes and how to fix them (with code)

Next.js 16 vs 15 isn’t just a version bump—it’s a set of decisions that directly affect speed, stability, and the total cost of ownership for your web app. If you care about faster builds, leaner navigation, and predictable caching, the Next.js 16 migration will matter to your roadmap and your ROI. It introduces a new caching model, a default switch to Turbopack, and a handful of breaking changes that you’ll want to tame before they bite in production 12.

For business owners and product leaders, here’s the punchline: your team can ship faster with fewer production surprises, and your users will see smoother navigation and more stable experiences. The better news? Most of the risky changes have clear, simple fixes. Let’s unpack what actually changed, what got faster, and exactly how to upgrade from Next.js 15 with confidence.

What’s new—and why it matters for the business

Next.js 16 shores up three areas that affect outcomes you feel on the P&L: development velocity, user-perceived speed, and operational predictability. Turbopack is now the default bundler for dev and build, cutting build times and accelerating hot updates. Routing and prefetching got smarter—reducing data transfer and making navigation feel “instant” to your customers. And the new Cache Components model makes caching explicit rather than “surprising,” which is a fancy way of saying fewer head-scratching incidents at 2 a.m. 1.

Next.js 15 vs 16 at a glance

The highlights below are from the official release notes and upgrade docs. They’re the practical bits you’ll notice on day one 12.

What’s faster in Next.js 16

You don’t need a benchmarking lab to feel the difference, but the headline numbers are useful for prioritization. According to the official release, Turbopack delivers 2–5× faster production builds and up to 10× faster Fast Refresh. Navigation is leaner thanks to layout deduplication and incremental prefetching that cut down on duplicate downloads, especially for link-heavy pages 1.

From a business point of view, these deltas add up. Faster builds compress cycle time between idea and release; faster refresh makes iteration feel effortless (which, shocker, teams do more of); and leaner navigations lower bandwidth while improving perceived speed—the part users actually notice.

If you want to experiment with the new caching approach, the Cache Components model centers on a simple directive that opts components into caching:

// app/page.tsx
"use cache";

export default async function Page() {
  // Any async data here is cached by key the compiler derives.
  // You can still tag or invalidate as needed.
  return <main>Welcome to Next.js 16</main>;
}

“

Tip: Cache Components are off by default and replace the older PPR flags. Turn them on in next.config.ts with cacheComponents: true 1.

The 7 breaking changes (and how to fix them)

Migrating from Next.js 15? These are the changes that can break builds or behavior. The fixes are straightforward; I’ll show you how to patch each one.

1) Dynamic APIs & route params are now async‑only

In Next.js 15, cookies, headers, draftMode, params, and searchParams could still be accessed synchronously (with warnings). In Next.js 16, synchronous access is removed. You must await them—even in page and layout files. Image metadata functions (opengraph-image, twitter-image, icon, apple-icon) now also receive Promise‑based params and IDs 2.

Fix: update your signatures and access patterns.

// Before (15 - sync access tolerated)
export default function Page({ params, searchParams }) {
  const slug = params.slug;
  const q = searchParams.q;
  return (
    <h1>
      {slug} — {q}
    </h1>
  );
}

// After (16 - async access required)
import type { PageProps } from "next"; // generated by `npx next typegen` (15.5+)

export default async function Page(props: PageProps<"/blog/[slug]">) {
  const { slug } = await props.params;
  const query = await props.searchParams;
  return (
    <h1>
      {slug} — {query.q}
    </h1>
  );
}

// Image metadata generators are async, too
export async function generateImageMetadata({ params }) {
  const { slug } = await params;
  return [{ id: "1" }];
}

export default async function Image({ params, id }) {
  const { slug } = await params;
  const imageId = await id;
  // ...
}

Use the codemod to speed this up:

npx @next/codemod@canary upgrade latest
# and, if needed for types:
npx next typegen

Why it matters: this unlocks a simpler, more predictable rendering pipeline and aligns with the new caching model, reducing “it worked locally” surprises 26.

2) middleware.ts becomes proxy.ts (Node runtime)

Next.js 16 introduces proxy.ts, which replaces middleware.ts for runtime request interception on Node. Rename the file and the default export, and note that configuration flags containing “middleware” are renamed (for example, skipMiddlewareUrlNormalize → skipProxyUrlNormalize). The old middleware.ts remains for Edge use cases but is deprecated 12.

Fix: rename & adjust.

// proxy.ts — Next.js 16
import { NextRequest, NextResponse } from "next/server";

export default function proxy(request: NextRequest) {
  if (request.nextUrl.pathname === "/") {
    return NextResponse.redirect(new URL("/home", request.url));
  }
  return NextResponse.next();
}

Why it matters: clearer boundaries and a single predictable runtime reduce debugging time and platform-specific edge cases 12.

3) Turbopack is the default (and config moved)

Turbopack is now the default bundler for next dev and next build, and the configuration moves from experimental.turbopack to a top‑level turbopack key. If you have custom Webpack configuration, a plain next build can fail to prevent silent misconfiguration. You can opt out temporarily with --webpack, but the recommendation is to switch 2.

Fix: update scripts & config.

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  turbopack: {
    // your options here
  },
};

export default nextConfig;

If you must keep Webpack during migration: next build --webpack 2.

Why it matters: faster builds and refresh mean tighter feedback loops and higher developer throughput; it’s tangible productivity 12.

4) next/image gets stricter: local images with query strings

To mitigate filesystem enumeration attacks, local images with query strings (e.g., /assets/photo?v=1) now require explicit configuration with images.localPatterns.search. Without it, those images break 2.

Fix: declare the pattern.

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  images: {
    localPatterns: [
      {
        pathname: "/assets/**",
        search: "v=*",
      },
    ],
  },
};

export default nextConfig;

Why it matters: better defaults shrink risk surface area without devs having to remember one‑off rules 2.

5) images.domains is deprecated → use remotePatterns

The older, broad images.domains allow‑list is replaced by images.remotePatterns, which is more precise and secure. If you relied on domains, you’ll need to migrate 2.

Fix: move to remote patterns.

// next.config.ts
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "images.example.com",
        pathname: "/cdn/**",
      },
    ],
  },
};

export default nextConfig;

Why it matters: tighter controls help you avoid supply‑chain surprises from overly permissive image sources 2.

6) next lint is removed (use ESLint CLI or Biome)

The next lint command is gone, and next build no longer runs linting for you. If your CI silently depended on this, it will stop linting after the upgrade 2.

Fix: run ESLint directly in scripts/CI.

There’s a codemod to migrate: npx @next/codemod@canary next-lint-to-eslint-cli . 2.

Why it matters: making linting explicit improves control and performance; you decide when (and where) to pay the cost 2.

7) serverRuntimeConfig / publicRuntimeConfig removed

Runtime configuration via next/config is removed. Use environment variables, and if you need to read them at request time (rather than bundled at build), call connection() first in a Server Component or Route Handler 2.

Fix: use env vars and connection().

// app/page.tsx
import { connection } from "next/server";

export default async function Page() {
  await connection(); // ensure runtime read
  const apiUrl = process.env.NEXT_PUBLIC_API_URL;
  return <p>API: {apiUrl}</p>;
}

Why it matters: simpler, platform‑agnostic configuration reduces lock‑in and build surprises 2.

Quick summary table — 7 breaking changes & fixes

Implementation notes, prerequisites, and sequencing

Two housekeeping items before you press the big green button. First, Node.js 20.9+ and TypeScript 5+ are now required. If you’re still on Node 18 or TS 4, upgrade those first or the install will fail 2. Second, if your app leans heavily on custom Webpack loaders, plan a short spike to map them to Turbopack equivalents or use the temporary --webpack opt‑out while you migrate 2.

Here’s a pragmatic migration sequence we’ve used with good results:

1. Upgrade engines and dependencies; run the codemod; turn on Turbopack by default.
2. Address async APIs and image defaults (they’re the most visible breakages).
3. Rename middleware.ts to proxy.ts and verify behavior with observability on.
4. Switch linting in CI to ESLint CLI.
5. Replace next/config usage with env variables, adding connection() where runtime reads are needed.

This order minimizes downtime and reduces the “death by a thousand papercuts” feeling during rollout.

For the performance‑minded: how to realize gains quickly

To get the most out of Next.js 16 immediately, start by enabling filesystem caching in development to shrink cold starts across restarts, and consider opting into the React Compiler if your component tree does a lot of prop plumbing. The compiler can eliminate a surprising amount of unnecessary re‑renders—at the cost of slower builds—so evaluate it per project 1.

Routing improvements require no code, but you can amplify them: aggressively prefetch critical paths, keep layouts slim, and tag cacheable content using the now-stable cacheLife / cacheTag helpers. When something needs “read‑your‑writes” semantics, use updateTag() in Server Actions; for general invalidation, revalidateTag(tag, "max") is the new, explicit path 12.

// app/actions.ts (Server Action)
"use server";

import { updateTag, revalidateTag } from "next/cache";

export async function updateUserProfile(userId: string, profile: any) {
  // write
  // await db.users.update(userId, profile);

  // immediate read-your-writes for this user
  updateTag(`user-${userId}`);
}

// elsewhere, to keep long-lived content fresh with SWR:
revalidateTag("blog-posts", "max");

The result is a caching strategy that matches business expectations: things that must update instantly do so; everything else stays fast and stable.

Business case: why upgrade now (not next quarter)

From an executive lens, “upgrade churn” looks like cost. But Next.js 16 is one of those releases where the platform pays you back. Default Turbopack means shorter build queues and fewer blocked engineers. Explicit caching translates into fewer production incidents and lower support load. And the routing work reduces bandwidth while making the product feel more responsive—good for conversion, retention, and search performance. Those are enduring benefits, not vanity metrics 12.

If you’re sitting on a sizable codebase, treat this like any other change initiative: isolate risk, run the codemods in a branch, and measure baseline build times, refresh speed, and navigation weight before/after. We’ve seen teams recoup upgrade effort within a few sprints because they simply ship more.

Conclusion

Next.js 16 brings tangible wins: faster builds, snappier navigation, and fewer “why did this cache?” mysteries. The seven breaking changes above can be fixed with clear, mechanical steps. If you adopt Turbopack fully and lean into the explicit caching model, you’ll have a codebase that’s not just faster—it’s calmer to operate.

If you’d like help implementing the migration or validating performance, our team at Blue Nebula is here to help.

References