Coder Legion - Recent posts tagged cache-components

Next.js Cache Components Migration Guide (2026)

Wed, 02 Sep 2026 04:01:53 +0000

You flip on cacheComponents: true expecting a quick performance win, and instead your build explodes with red errors about dynamic, revalidate, and fetchCache not being allowed anymore. Then, once those clear, the dev overlay starts flagging routes that "won't render instantly" — pointing at cookies(), searchParams, and database calls you've had in production for months.

Nothing is actually broken. This is exactly how the migration is supposed to work — Next.js is walking you through moving from implicit caching (where the framework guessed what should be static) to explicit caching (where you say so directly). This guide walks through that migration end to end: every route segment config you'll need to replace, what to swap it for, and how to do it without rewriting your whole app in one sitting.

💡 New to Cache Components as a concept? This guide is about migrating an existing app. If you want the "what and why" first, read Next.js Rendering Strategies Explained, which covers SSR, SSG, ISR, and Cache Components from scratch.

Why This Migration Exists

Before Cache Components, Next.js decided whether a route was static or dynamic for you, by inspecting what your code touched — a fetch call, a cookies() read, a route segment config. That worked, but it was implicit: two developers could read the exact same route and disagree about whether it was static or dynamic, and a small code change could silently flip a page from instant to slow.

Cache Components flips the default: everything is dynamic (rendered per-request) unless you explicitly mark it as cached. You use 'use cache' to say "cache this," cacheLife() to say "for how long," and <Suspense> to say "this part is allowed to be slow, stream it in separately." Nothing is guessed anymore.

This is also what powers Partial Prerendering (PPR) as the default behavior — a page can ship a static, instantly-served HTML shell while a personalized or slow-loading section streams in right behind it, all in one route, with no extra config.

Prerequisites

This guide assumes:

Next.js 16 — Cache Components requires it. If you're on Next.js 15 with experimental.dynamicIO or experimental.ppr, upgrade to 16 first using the official upgrade guide.
App Router — Cache Components is an App Router feature only. It does nothing for a pages/ directory. A hybrid app (both pages/ and app/) is fine — the flag only affects app/ routes.
TypeScript in strict mode (the examples below use it, but everything works the same in plain JS).
Node.js runtime — Cache Components does not support runtime = 'edge'. More on this later.

Step 1: Enable the `cacheComponents` Flag

Turn it on in your config file.

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

const nextConfig: NextConfig = {
  cacheComponents: true,
};

export default nextConfig;

What's happening here: this single flag replaces three older, separate flags — experimental.dynamicIO, experimental.useCache, and experimental.ppr. If your next.config.ts still has any of those, delete them; cacheComponents supersedes all three.

⚠️ Common Mistake: Leaving experimental.ppr or experimental_ppr route segment exports in place after adding cacheComponents. Next.js 16 removed the experimental.ppr flag entirely — PPR is just what cacheComponents does now. Run npx @next/codemod@canary to clean up leftover experimental_ppr segment exports automatically (see the codemod list in the official codemods reference).

The moment you save this file, any route that still exports dynamic, revalidate, or fetchCache will fail to build. That's expected — those three route segment configs no longer exist under Cache Components, and the rest of this guide is about replacing each one.

Step 2: Pick Your Migration Strategy

You have two realistic paths, and the right one depends on how big your app is.

Option A — Migrate everything now

Fine for small apps or a handful of routes. Go through each error the build throws, fix it, move to the next.

Option B — Migrate incrementally (recommended for real apps)

Use the instant route segment config to defer validation on routes you're not ready to touch yet, so the rest of your app keeps shipping while you convert routes one at a time.

// app/dashboard/layout.tsx
export const instant = false;

What's happening here: instant = false tells Next.js "this segment is allowed to block on request-time work — don't fail the build over it yet." It does not force the route to become fully dynamic; a route that's actually prerenderable still ships a static shell even with this set. It just silences the validation error so you can come back to it later.

Next.js ships a codemod that adds this opt-out to every page, layout, and default file in one pass:

npx @next/codemod@canary cache-components-instant-false ./app

💡 Tip: If your app lives under src/app, pass that exact path instead — npx @next/codemod@canary cache-components-instant-false ./src/app. A wrong path silently reports 0 ok instead of erroring, so check the file count in the output before assuming it worked.

With that run, your whole app builds and serves again. Then work through routes one at a time: remove instant = false from a segment, fix whatever the dev overlay flags, repeat.

⚠️ instant = false doesn't fix everything. Synchronous, non-deterministic calls — new Date(), Date.now(), Math.random(), crypto.randomUUID() — used during prerender still throw a hard build error that this opt-out does not suppress. Move the call into a component wrapped in <Suspense> (calling connection() first) or into a Client Component instead.

Step 3: Remove `dynamic = 'force-dynamic'`

This one's the easiest fix in the whole migration — you just delete it.

// Before
export const dynamic = "force-dynamic";

export default function Page() {
  return <div>...</div>;
}

// After — every route is already dynamic by default
export default function Page() {
  return <div>...</div>;
}

Why: under Cache Components, nothing is cached unless you say so with 'use cache'. "Dynamic by default" is now the baseline behavior, so force-dynamic has nothing left to force.

Step 4: Replace `dynamic = 'force-static'` with `'use cache'`

Start by deleting the export, then let the build tell you what's actually uncached.

// Before
export const dynamic = "force-static";

export default async function Page() {
  const data = await fetch("https://api.example.com/data");
  return <div>...</div>;
}

// After
import { cacheLife } from "next/cache";

export default async function Page() {
  "use cache";
  cacheLife("max");

  const data = await fetch("https://api.example.com/data");
  return <div>...</div>;
}

What's happening here: use cache at the top of the function marks it as a cache boundary — everything inside, including the fetch call, gets cached automatically. cacheLife('max') is the closest built-in profile when you want long-lived caching, but it is not a literal equivalent of the old force-static behavior.

If your force-static route reads runtime data (cookies(), headers()), you can't keep it fully static anymore — that data genuinely only exists per-request. The fix there is wrapping just that part in <Suspense>, covered in Step 9.

Step 5: Replace `revalidate` with `cacheLife`

A numeric revalidate export becomes a cacheLife() call inside a 'use cache' function.

// Before
export const revalidate = 3600; // 1 hour

export default async function Page() {
  return <div>...</div>;
}

// After
import { cacheLife } from "next/cache";

export default async function Page() {
  "use cache";
  cacheLife("hours");

  return <div>...</div>;
}

What's happening here: cacheLife accepts either a named profile string or a custom object. The built-in profiles — seconds, minutes, hours, days, weeks, max — map to sensible defaults:

Profile	`stale`	`revalidate`	`expire`
`seconds`	30s	1s	1 min
`minutes`	5 min	1 min	1 hour
`hours`	5 min	1 hour	1 day
`days`	5 min	1 day	1 week
`weeks`	5 min	1 week	30 days
`max`	5 min	30 days	1 year

If none of the presets match your old revalidate value exactly, pick the closest one, or define a custom profile in next.config.ts:

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

const nextConfig: NextConfig = {
  cacheComponents: true,
  cacheLife: {
    blog: {
      stale: 3600, // 1 hour — how long the client can use a cached value without checking
      revalidate: 900, // 15 minutes — how often the server refreshes in the background
      expire: 86400, // 1 day — max age before the entry is dropped entirely
    },
  },
};

export default nextConfig;

stale controls how long the client Router Cache can reuse the result; it does not set the HTTP Cache-Control: max-age header.

// app/blog/page.tsx
import { cacheLife } from "next/cache";

export default async function BlogPage() {
  "use cache";
  cacheLife("blog"); // references the custom profile above

  return <div>...</div>;
}

💡 Tip: You can also redefine a built-in profile (including default) with the same name, if you want cacheLife('hours') to mean something different across your whole app. Document it somewhere obvious if you do — a teammate reading cacheLife('hours') will otherwise assume the stock 1-hour behavior.

Step 6: Delete `fetchCache`

This route segment config has no replacement because it has no purpose anymore.

// Before
export const fetchCache = "force-cache";

// After — just delete it
export default async function Page() {
  "use cache";
  // every fetch() inside this scope is cached automatically
  return <div>...</div>;
}

Why: fetchCache used to control whether fetch() calls were cached at the route level. Under Cache Components, caching is decided per-function by 'use cache', not globally per route — so there's nothing left for fetchCache to configure.

Step 7: Move `fetch()` Cache Options into `'use cache'`

Move the caching policy into the use cache scope and replace fetch-level tags with cacheTag() where appropriate.

// Before
export default async function Page() {
  const res = await fetch("https://api.example.com/data", {
    cache: "force-cache",
    next: { revalidate: 3600, tags: ["data"] },
  });
  const data = await res.json();
  return <div>...</div>;
}

// After
import { cacheLife, cacheTag } from "next/cache";

async function getData() {
  "use cache";
  cacheLife("hours");
  cacheTag("data");

  const res = await fetch("https://api.example.com/data");
  return res.json();
}

export default async function Page() {
  const data = await getData();
  return <div>...</div>;
}

What's happening here: pulling the fetch into its own getData() function marked 'use cache' is the standard pattern — it keeps the cache boundary small and lets the page component stay a plain async function. cacheTag('data') is what lets you invalidate this specific cached result later (Step 9).

⚠️ Persistence difference worth knowing: the old fetch Data Cache persisted across deployments and serverless instances. By default, 'use cache' uses an in-memory cache isolated to the Next.js process. Multiple instances do not share that cache, and entries are lost when the process restarts. If you need caching that survives instance teardown, use 'use cache: remote' or configure a cache handler. Either way, expect values to recompute after a fresh deployment.

Step 8: Replace `unstable_cache` with `'use cache'`

If you were wrapping database queries in unstable_cache, the migration is mechanical.

// Before
import { unstable_cache } from "next/cache";
import { db } from "@/lib/db";

export const getUser = unstable_cache(
  async (id: string) => {
    return db.query.users.findFirst({ where: eq(users.id, id) });
  },
  ["user"], // cache key prefix
  { tags: ["users"], revalidate: 3600 }
);

// After
import { cacheLife, cacheTag } from "next/cache";
import { db } from "@/lib/db";

export async function getUser(id: string) {
  "use cache";
  cacheLife("hours");
  cacheTag("users");

  return db.query.users.findFirst({ where: eq(users.id, id) });
}

What's happening here: the wrapper function becomes a plain function with a directive. Notice the manual ["user"] cache-key-prefix array is gone entirely — Next.js derives the cache key automatically from the function's arguments (and its closure), so you never write a cache key by hand.

Same persistence caveat as Step 7 applies: unstable_cache persisted across deployments; 'use cache' doesn't by default.

Step 9: Update Your Invalidation Calls

On-demand invalidation still works — you just have three tools now instead of one, and picking the right one matters.

updateTag — for a mutation where the user needs to see their own change immediately (read-your-own-writes). Only callable from a Server Action.
revalidateTag — for stale-while-revalidate behavior. Works in both Server Actions and Route Handlers, but now requires a cache profile as a second argument.
revalidatePath — unchanged from before.

// app/actions.ts
"use server";

import { updateTag } from "next/cache";

export async function createPost(formData: FormData) {
  // create the post in your database, then:
  updateTag("posts"); // the next render sees the new post immediately
}

// app/api/webhook/route.ts

// Before
import { revalidateTag } from "next/cache";

export async function POST() {
  revalidateTag("posts");
  return Response.json({ ok: true });
}

// app/api/webhook/route.ts

// After — a profile is now required
import { revalidateTag } from "next/cache";

export async function POST() {
  revalidateTag("posts", "max");
  return Response.json({ ok: true });
}

What's happening here: the bare, single-argument revalidateTag(tag) call is deprecated — it still technically compiles if you suppress the TypeScript error, but it may stop working in a future release. Pass max as the recommended default — it uses the profile's one-year expire value as the stale-serving window, so requests almost never block waiting on a fresh fetch after invalidation.

⚠️ Common Mistake: Reaching for revalidateTag after a mutation when you actually want updateTag. revalidateTag marks data stale and serves the old value while it refreshes in the background — a user who just submitted a form could still see their old data on the very next page load. If the user needs to see their own change right away, use updateTag inside the Server Action instead.

Step 10: Delete `unstable_noStore`

Remove unstable_noStore() in most migrations. If the operation must intentionally happen at request time and doesn't naturally depend on cookies(), headers(), or another request API, use connection() to opt that work out of prerendering.

// Before
import { unstable_noStore as noStore } from "next/cache";

export default async function Page() {
  noStore();
  const data = await db.query("...");
  return <div>...</div>;
}

// After
export default async function Page() {
  const data = await db.query("...");
  return <div>...</div>;
}

If a component genuinely needs to run at request time (not just "not be cached"), call connection() before the work and wrap it in <Suspense> — that's the real replacement when you need to force a dynamic boundary rather than just skip caching.

Step 11: Fix `generateStaticParams`

Two real changes here for dynamic routes.

An empty array is now an error

// Before — used to defer every path to runtime, now throws a build error
export async function generateStaticParams() {
  return [];
}

// After — return at least one param so Next.js can prerender a shell
export async function generateStaticParams() {
  const posts = await fetch("https://.../posts").then((res) => res.json());
  return posts.slice(0, 1).map((post: { slug: string }) => ({ slug: post.slug }));
}

Why: Cache Components needs generateStaticParams to produce at least one real param so it can prerender a static shell and confirm it's non-empty. Paths you don't return still work fine — Next.js prerenders a generic shell for unknown params and streams the real content at request time.

`dynamicParams` is no longer supported

// Before — this now fails the build entirely
export const dynamicParams = false;

Delete it. If you were using dynamicParams: false to reject unknown params, call notFound() inside the page instead, once you know the param doesn't resolve to real data.

Await `params` inside `<Suspense>`, not at the top

// Before — awaiting at the top blocks the whole static shell
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  return <Post slug={slug} />;
}

// After
import { Suspense } from "react";

export default function Page({ params }: PageProps<"/blog/[slug]">) {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Post params={params} />
    </Suspense>
  );
}

async function Post({ params }: Pick<PageProps<"/blog/[slug]">, "params">) {
  const { slug } = await params;
  // ...
}

What's happening here: passing the params promise straight through as a prop, then awaiting it inside a <Suspense>-wrapped child, lets Next.js prerender the shell for unknown/unlisted params instead of blocking the entire page on resolving them first.

The same pattern applies to usePathname, useParams, useSelectedLayoutSegment, useSelectedLayoutSegments, and useSearchParams in Client Components — if the value depends on a dynamic param, wrap the smallest component that reads it in <Suspense> rather than the whole tree.

Step 12: Wrap `cookies()`, `headers()`, and `searchParams` in `<Suspense>`

This is the change you'll hit most often, because it's the most common source of "instant navigation" validation errors.

// Before — reading cookies at the top makes the whole route dynamic
import { cookies } from "next/headers";

export default async function Page() {
  const theme = (await cookies()).get("theme")?.value;
  return <Dashboard theme={theme} />;
}

// After — the page shell prerenders; only Dashboard streams at request time
import { cookies } from "next/headers";
import { Suspense } from "react";

export default function Page() {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <Dashboard />
    </Suspense>
  );
}

async function Dashboard() {
  const theme = (await cookies()).get("theme")?.value;
  // ...
}

What's happening here: moving the cookies() read into a separate component, and wrapping just that component in <Suspense>, lets everything outside it (the page's static shell) prerender normally. Only the part that genuinely needs per-request data waits until the actual request.

The same move applies to searchParams, which your page receives as a promise:

import { Suspense } from "react";

export default function Page({ searchParams }: PageProps<"/">) {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <Results searchParams={searchParams} />
    </Suspense>
  );
}

async function Results({ searchParams }: Pick<PageProps<"/">, "searchParams">) {
  const { query } = await searchParams;
  // ...
}

💡 Tip: If a cookie or header controls an attribute on <html> in the root layout (lang, dir, data-theme), there's no child element to wrap in <Suspense> — reading it there makes the whole subtree request-bound by nature. Use an inline <script> in <head> that sets the attribute client-side before paint instead; see Preventing flash before hydration for the pattern.

Step 13: Update `GET` Route Handlers

Route Handlers follow the same rules as pages now.

// app/api/products/route.ts

// Before
export const dynamic = "force-static";

export async function GET() {
  const products = await db.query("SELECT * FROM products");
  return Response.json(products);
}

// app/api/products/route.ts

// After
import { cacheLife } from "next/cache";

export async function GET() {
  const products = await getProducts();
  return Response.json(products);
}

async function getProducts() {
  "use cache";
  cacheLife("hours");

  return db.query("SELECT * FROM products");
}

What's happening here: the 'use cache' directive can't be applied to the exported GET function itself — it goes on a helper function the handler calls instead.

💡 Tip: Reading uncached or runtime data in a GET handler bails out of prerendering by throwing. If you already wrap your handler body in try/catch, that block will catch this bail-out too — which can add noisy logs during the build. Set experimental.hideLogsAfterAbort: true in next.config.ts if that gets in your way.

Step 14: Handle `generateMetadata` and `generateViewport`

These follow the same component rules — cache external data, or explicitly mark the page as needing runtime data.

// Before
export async function generateMetadata() {
  const { title, description } = await db.query("site-metadata");
  return { title, description };
}

// After — cache it, same as any other external data fetch
export async function generateMetadata() {
  "use cache";
  const { title, description } = await db.query("site-metadata");
  return { title, description };
}

If your metadata genuinely depends on runtime data (a signed-in user's name, a cookie), you can't wrap generateMetadata itself in <Suspense> — instead, add a small dynamic marker component to the page so the static content still prerenders while the metadata resolves separately:

import { Suspense } from "react";
import { connection } from "next/server";

export async function generateMetadata() {
  // reads runtime data — intentional
  return { title: "Personalized Title" };
}

async function Connection() {
  await connection();
  return null;
}

export default function Page() {
  return (
    <>
      <article>Static content</article>
      <Suspense>
        <Connection />
      </Suspense>
    </>
  );
}

For the full breakdown of trade-offs here, see generateMetadata with Cache Components in the official reference — this is one of the trickier corners of the migration and worth reading directly if metadata personalization matters for your app. If you haven't set up metadata at all yet, How to Add Metadata in Next.js 16 covers the basics first.

Step 15: Remove `runtime = 'edge'`

Cache Components requires the Node.js runtime — Edge isn't supported.

// Before — no longer supported under Cache Components
export const runtime = "edge";

Delete the export (Node.js is the default anyway). If you specifically need Edge behavior for a route — geolocation checks, ultra-low-latency redirects — reach for Proxy (the renamed middleware.ts) instead of the Edge runtime on the route itself.

A Gotcha After the Build Passes: UI State No Longer Resets

Once your routes build cleanly, there's one behavior change worth testing manually, because it won't show up as a build error: Cache Components preserves component state across client-side navigation using React's <Activity> component, instead of unmounting the page you navigated away from.

In practice: a useState value, an open dropdown, or scroll position no longer resets just because the user clicked to a different page and back. This is usually a win, but it can surface bugs in code that assumed navigating away meant a clean remount — a dropdown that used to close automatically, a dialog whose focus-on-open effect no longer refires because its state was preserved rather than reset.

⚠️ Common Mistake: Assuming a modal or dropdown will close itself on navigation the way it always used to. If a component should reset when its route or user context changes, reset that state explicitly based on the relevant prop/route change instead of relying on unmount behavior.

Migration Checklist

Work through this in order for each route:

[ ] cacheComponents: true set in next.config.ts; old experimental.dynamicIO / experimental.useCache / experimental.ppr removed
[ ] dynamic = 'force-dynamic' deleted everywhere
[ ] dynamic = 'force-static' replaced with 'use cache' + cacheLife('max')
[ ] revalidate exports replaced with cacheLife() calls
[ ] fetchCache exports deleted
[ ] Individual fetch() cache options (cache, next.revalidate, next.tags) moved into 'use cache' functions with cacheLife / cacheTag
[ ] unstable_cache calls converted to 'use cache' functions
[ ] revalidateTag calls updated to pass a cache profile (revalidateTag(tag, 'max'))
[ ] Mutations that need read-your-own-writes use updateTag instead of revalidateTag
[ ] unstable_noStore() calls removed
[ ] generateStaticParams returns at least one param; dynamicParams export removed
[ ] params and searchParams awaited inside <Suspense>-wrapped children, not at the top of the page
[ ] cookies() / headers() reads pushed into <Suspense>-wrapped components
[ ] GET Route Handlers use a 'use cache' helper instead of dynamic = 'force-static'
[ ] generateMetadata / generateViewport cache external data or use the dynamic-marker pattern for runtime data
[ ] No routes still export runtime = 'edge'
[ ] UI that relied on unmount-to-reset behavior (dropdowns, dialogs, forms) tested manually after migration

Frequently Asked Questions

Do I have to migrate my whole app at once?

No. Use export const instant = false on the layouts or pages that aren't ready, run the cache-components-instant-false codemod to apply it everywhere in one pass, and convert routes one at a time from there. Your app keeps building and serving the whole time.

What happens to my existing `fetch` cache and `unstable_cache` data during migration?

Existing unstable_cache usage is still supported, but Next.js 16 recommends migrating it to use cache. The old fetch/Data Cache model and Cache Components can coexist during migration, but route segment configs such as dynamic, revalidate, and fetchCache must be migrated.

Why does my build fail on `new Date()` even with `instant = false` set?

instant = false only defers the validation check for whether a route renders instantly — it doesn't clear synchronous, non-deterministic calls like new Date(), Math.random(), or crypto.randomUUID() used during prerendering. Those still throw a hard build error. Move the call into a <Suspense>-wrapped component (calling connection() first) or into a Client Component.

Is `'use cache'` the same as the old `fetch` Data Cache?

No, and this trips people up. The old fetch Data Cache persisted across deployments and serverless instances. The default use cache handler uses an in-memory LRU cache isolated to each Next.js process. It isn't shared across multiple instances and is lost when the process restarts. Use use cache: remote or a cache handler if you need durability across deployments.

My `revalidateTag(tag)` call now shows a TypeScript error — what changed?

The single-argument form is deprecated. revalidateTag now requires a cache profile as a second argument — revalidateTag('posts', 'max') uses the recommended stale-while-revalidate profile. The max cache profile has a 30-day server revalidation interval and a 1-year expiration window.

Does Cache Components work with the Pages Router?

No — it's an App Router-only feature. If your project has both pages/ and app/ directories, cacheComponents: true only affects the app/ routes; pages/ routes are completely unaffected and need no changes.

Can I use Cache Components on Vercel's Edge Runtime?

No. Cache Components requires the Node.js runtime. Remove any runtime = 'edge' export from routes you're migrating — if you specifically need Edge-level behavior, use Proxy (proxy.ts) instead of the route-level Edge runtime.

Wrapping Up

The Cache Components migration looks scary because it surfaces every implicit assumption your app was making about what's static versus dynamic, all at once, as build errors. But each fix is genuinely mechanical: revalidate becomes cacheLife, unstable_cache becomes a 'use cache' function, and any runtime data read (cookies(), searchParams, a live database query) gets pushed into a <Suspense> boundary so it doesn't block the rest of the page.

Start with instant = false on everything you're not ready to touch, get the app building again, then convert routes one at a time using the checklist above. You'll come out the other side with a codebase where every cache decision is explicit instead of guessed — and a meaningfully faster app for it.

Continue Learning

Useful Resources

Next.js Rendering Strategies Explained: SSR, SSG, CSR, ISR & Cache Components (2026)

Tue, 28 Jul 2026 10:32:23 +0000

Ever opened the Next.js docs and seen acronyms like SSR, SSG, CSR, and ISR thrown around like everyone's supposed to just know what they mean? You're not alone. Half the confusion around Next.js performance comes down to one simple question nobody explains clearly enough: when does your page actually get built — and where?

Once you understand that one question, every rendering strategy in Next.js suddenly makes sense. By the end of this guide, you'll know exactly what SSR, SSG, CSR, and ISR mean, how the newer Cache Components model (powered by Partial Prerendering, or PPR) ties it all together, and which one to reach for in your own projects.

Why This Matters

Every page you build has to answer one question: "When should the HTML for this page get generated?"

There are really only three possible answers:

Ahead of time, during next build — before any user even visits the site.
On request, every time a user visits — generated fresh on the server.
In the browser, after the page loads — generated by JavaScript running on the user's device.

Next.js gives you a strategy for each answer, plus a smart hybrid (Cache Components) that mixes them on the same page. Here's the whole picture at a glance before we go through each one:

What Is SSR (Server-Side Rendering)?

💡 Think of it like: ordering food at a restaurant — you ask, the kitchen cooks it fresh, then it's served to you. Every single time.

SSR means the HTML for a page is generated on the server, for every single request. The user always gets fresh data, but the server has to do work on every visit.

In the Next.js App Router, you get SSR automatically whenever a page reads something that can only be known at request time — like cookies, headers, or search params — or when you explicitly opt a page into dynamic rendering.

// app/dashboard/page.tsx
import { cookies } from "next/headers";

export default async function DashboardPage() {
  const cookieStore = await cookies();
  const userId = cookieStore.get("userId")?.value;

  const res = await fetch(`https://api.example.com/users/${userId}`, {
    cache: "no-store", // tells Next.js: never cache this, always fetch fresh
  });
  const user = await res.json();

  return <h1>Welcome back, {user.name}</h1>;
}

What's happening here: because we read cookies() and pass cache: "no-store" to fetch, Next.js knows this page depends on request-specific data. It renders the page on the server every time someone visits, instead of reusing a cached copy.

Use SSR when:

The content is personalized per user (dashboards, account pages).
Data changes frequently and must always be fresh (stock prices, live order status).

⚠️ Common Mistake: Using SSR for content that rarely changes (like a blog post) wastes server resources. If the data isn't user-specific or constantly changing, you probably want SSG or ISR instead.

What Is SSG (Static Site Generation)?

💡 Think of it like: a printed menu — it's made once, in advance, and handed to every customer exactly the same.

SSG means the HTML is generated once, at build time, and then reused for every visitor. No server work happens per request — Next.js just serves the same pre-built HTML file.

// app/blog/[slug]/page.tsx
import { getPostBySlug, getAllPosts } from "@/lib/posts";

// This tells Next.js which pages to pre-build at build time
export async function generateStaticParams() {
  const posts = getAllPosts();
  return posts.map((post) => ({ slug: post.slug }));
}

export default async function BlogPostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = getPostBySlug(slug);

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.description}</p>
    </article>
  );
}

What's happening here: generateStaticParams() tells Next.js exactly which blog post pages exist. At build time, Next.js renders each one into static HTML. When a real visitor requests /blog/my-post, the server just hands over the already-built file — no rendering work, no database hit, nothing. It's instant.

Use SSG when:

Content doesn't change often (blog posts, marketing pages, documentation).
You want the fastest possible load times and lowest server cost.

⚠️ Common Mistake: If your content updates frequently but you're using pure SSG, visitors will keep seeing stale data until you rebuild and redeploy the entire site. That's exactly the problem ISR solves — keep reading.

What Is CSR (Client-Side Rendering)?

💡 Think of it like: ordering a build-it-yourself meal kit — the server hands you the box and instructions (a minimal HTML shell), but your browser does the actual cooking (fetching data and rendering the final content).

A common misconception is that CSR means the server does nothing. It doesn't — Next.js still renders and sends a minimal HTML shell from the server for Client Components (usually the loading/empty state). What makes it "client-side" is that the data fetching and the final content render happen in the browser, after JavaScript downloads and runs. The browser then "hydrates" that HTML — attaching event listeners and making it interactive — before fetching data and re-rendering with the real content.

In Next.js, you get CSR by using Client Components with hooks like useState and useEffect (or a data-fetching library like React Query).

// components/live-notifications.tsx
"use client";

import { useEffect, useState } from "react";

type Notification = { id: string; message: string };

export function LiveNotifications() {
  const [notifications, setNotifications] = useState<Notification[]>([]);

  useEffect(() => {
    fetch("/api/notifications")
      .then((res) => res.json())
      .then(setNotifications);
  }, []);

  return (
    <ul>
      {notifications.map((n) => (
        <li key={n.id}>{n.message}</li>
      ))}
    </ul>
  );
}

What's happening here: the "use client" directive tells Next.js this component should be interactive in the browser. The server sends an initial HTML shell (which may contain little or no real data), then the browser fetches data and renders the final UI after hydration. Once JavaScript loads and hydrates that HTML, useEffect fires, fetches data from /api/notifications, and re-renders the list with real content — all in the browser.

Use CSR when:

The content is highly interactive and user-specific (notification feeds, live chat, dashboards that update constantly).
SEO doesn't matter for that specific piece of UI (search engines don't need to see it).

⚠️ Common Mistake: Making your entire page a Client Component "just to be safe." This kills SEO and slows down the initial load. Only mark the interactive parts as client components — let everything else stay on the server.

What Is ISR (Incremental Static Regeneration)?

💡 Think of it like: a printed menu that quietly reprints itself in the background every hour — customers always get a menu instantly, and it's rarely more than an hour out of date.

ISR is SSG's smarter sibling. Pages are still pre-built and served instantly like static pages, but Next.js automatically regenerates them in the background after a set amount of time, without you needing to rebuild and redeploy your whole app.

// app/products/[id]/page.tsx
async function getProduct(id: string) {
  const res = await fetch(`https://api.example.com/products/${id}`, {
    next: { revalidate: 3600 }, // regenerate this page at most once every hour
  });
  return res.json();
}

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const product = await getProduct(id);

  return (
    <div>
      <h1>{product.name}</h1>
      <p>${product.price}</p>
    </div>
  );
}

What's happening here: revalidate: 3600 tells Next.js "this page can be served from cache for up to 3,600 seconds (1 hour)." The first visitor after that hour expires still gets the old cached page instantly — but Next.js triggers a regeneration in the background, so the next visitor gets the updated version. Nobody ever waits for a rebuild.

Use ISR when:

Content changes occasionally, but not so often that it needs to be SSR (product pages, pricing pages, news listings).
You want the speed of static pages without manually rebuilding every time data changes.

What Are Cache Components (and PPR)?

This is where things get genuinely exciting — and where most beginner tutorials stop short.

💡 Think of it like: a restaurant table that's already set, with bread on it the moment you sit down (static shell) — while your actual hot meal (dynamic content) is still being cooked and gets brought out the second it's ready.

Cache Components is Next.js's newer model for controlling caching explicitly, and it's what powers Partial Prerendering (PPR) under the hood. Instead of choosing one rendering strategy for an entire page, PPR lets a single page mix static and dynamic content together.

Here's the key idea: Next.js pre-renders a static "shell" of your page instantly (the parts that don't depend on the current request), and then streams in the dynamic parts as soon as they're ready — all without making the visitor wait for the slowest piece of data.

Step 1: Enable Cache Components

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

const nextConfig: NextConfig = {
  cacheComponents: true, // turns on the Cache Components / PPR model
};

export default nextConfig;

💡 Tip: Once cacheComponents is enabled, Next.js stops caching things implicitly. You now have to explicitly mark what should be cached using "use cache" — this makes caching predictable instead of "magic."

Step 2: Mark cacheable parts with `"use cache"`

// app/store/page.tsx
import { Suspense } from "react";
import { CartStatus } from "@/components/cart-status";

async function FeaturedProducts() {
  "use cache"; // this function's result gets cached and reused

  const res = await fetch("https://api.example.com/products/featured");
  const products = await res.json();

  return (
    <ul>
      {products.map((p: { id: string; name: string }) => (
        <li key={p.id}>{p.name}</li>
      ))}
    </ul>
  );
}

export default function StorePage() {
  return (
    <div>
      <h1>Welcome to the Store</h1>

      {/* Static shell — cached, renders instantly */}
      <FeaturedProducts />

      {/* Dynamic hole — depends on the current user, streams in separately */}
      <Suspense fallback={<p>Loading your cart...</p>}>
        <CartStatus />
      </Suspense>
    </div>
  );
}

What's happening here: FeaturedProducts has "use cache" at the top, so Next.js treats it as part of the static shell — it's pre-rendered and reused across visitors, just like SSG. CartStatus, on the other hand, depends on who's visiting (their cart), so it's wrapped in <Suspense>. Next.js sends the static shell (heading + featured products) instantly, then streams in the cart status the moment it's ready — without blocking the rest of the page.

This is the best of every world: the instant load of SSG, the freshness of SSR, all on the same page, without you manually choosing one strategy for the whole route.

💡 Tip: You can control how long cached content lives using cacheLife() (time-based expiry) and invalidate it on demand using cacheTag() + revalidateTag() — similar in spirit to ISR's revalidate, but with much finer control over what gets invalidated and when.

⚠️ Common Mistake: Don't put "use cache" on a function that returns data specific to the logged-in user with the default (shared) cache — that data could end up served to other users. Use "use cache: private" for personalized cached content instead.

Quick Comparison

Strategy	When HTML is built	Best for	Server load per request	SEO
SSR	On every request	Personalized, frequently changing data	High	Excellent
SSG	Once, at build time	Content that rarely changes	None	Excellent
CSR	Minimal shell on server, content rendered in browser after hydration	Highly interactive, non-SEO UI	Low (just the shell)	Depends
ISR	At build time + periodic background refresh	Content that changes occasionally	Low	Excellent
Cache Components (PPR)	Mixed — static shell instantly, dynamic parts streamed	Pages with both static and personalized sections	Only for the dynamic parts	Excellent

Frequently Asked Questions

Do I have to pick one strategy for my whole app?

No — and that's the whole point of Cache Components. You can mix strategies per page, and with PPR, even within the same page. Most real-world Next.js apps use a combination of all of these depending on the route.

Is ISR the same as Cache Components?

Not quite. ISR revalidates an entire page on a timer. Cache Components give you finer control — you choose exactly which functions or components get cached, for how long, and how they get invalidated, all while letting other parts of the same page stay dynamic.

Will Cache Components replace ISR completely?

For new projects using cacheComponents: true, yes — "use cache" with cacheLife() covers what revalidate used to do, plus more. Existing apps using the older caching model can keep working as-is, but new apps are encouraged to adopt Cache Components.

Does SSR hurt my SEO?

No — search engines see fully rendered HTML either way with SSR, SSG, or ISR. CSR is the one to watch, since content rendered purely in the browser can be harder for some crawlers to index reliably.

How do I know which strategy a page is using?

Run next build and check the build output — Next.js labels each route as Static, Dynamic, or Partial Prerendered (when Cache Components is enabled), so you can see exactly how each page will behave in production.

💡 Tip: Always test caching behavior with next build && next start rather than next dev — caching behaves differently in development mode and can be misleading.

Wrapping Up

Rendering strategy isn't a one-time architectural decision anymore — it's a per-component choice. SSR gives you freshness, SSG gives you speed, CSR gives you interactivity, ISR gives you a balance between the two static options, and Cache Components (powered by PPR) let you combine all of it on a single page without compromise.

Start simple: default to SSG/ISR for content-heavy pages, reach for SSR only when you genuinely need per-request freshness, and once you're comfortable, experiment with Cache Components to squeeze instant load times out of pages that still need personalized data.

Decision Tree

Is content personalized?
→ SSR

Is content mostly static?
→ SSG

Does it update occasionally?
→ ISR

Is it highly interactive UI?
→ CSR

Need static + dynamic on same page?
→ Cache Components / PPR

Coder Legion - Recent posts tagged cache-components

Next.js Cache Components Migration Guide (2026)

Why This Migration Exists

Prerequisites

Step 1: Enable the cacheComponents Flag

Step 2: Pick Your Migration Strategy

Option A — Migrate everything now

Option B — Migrate incrementally (recommended for real apps)

Step 3: Remove dynamic = 'force-dynamic'

Step 4: Replace dynamic = 'force-static' with 'use cache'

Step 5: Replace revalidate with cacheLife

Step 6: Delete fetchCache

Step 7: Move fetch() Cache Options into 'use cache'

Step 8: Replace unstable_cache with 'use cache'

Step 9: Update Your Invalidation Calls

Step 10: Delete unstable_noStore

Step 11: Fix generateStaticParams

An empty array is now an error

dynamicParams is no longer supported

Await params inside <Suspense>, not at the top

Step 12: Wrap cookies(), headers(), and searchParams in <Suspense>

Step 13: Update GET Route Handlers

Step 14: Handle generateMetadata and generateViewport

Step 15: Remove runtime = 'edge'

A Gotcha After the Build Passes: UI State No Longer Resets

Migration Checklist

Frequently Asked Questions

Do I have to migrate my whole app at once?

What happens to my existing fetch cache and unstable_cache data during migration?

Why does my build fail on new Date() even with instant = false set?

Is 'use cache' the same as the old fetch Data Cache?

My revalidateTag(tag) call now shows a TypeScript error — what changed?

Does Cache Components work with the Pages Router?

Can I use Cache Components on Vercel's Edge Runtime?

Wrapping Up

Continue Learning

Useful Resources

Next.js Rendering Strategies Explained: SSR, SSG, CSR, ISR & Cache Components (2026)

Why This Matters

What Is SSR (Server-Side Rendering)?

What Is SSG (Static Site Generation)?

What Is CSR (Client-Side Rendering)?

What Is ISR (Incremental Static Regeneration)?

What Are Cache Components (and PPR)?

Step 1: Enable Cache Components

Step 2: Mark cacheable parts with "use cache"

Quick Comparison

Frequently Asked Questions

Do I have to pick one strategy for my whole app?

Is ISR the same as Cache Components?

Will Cache Components replace ISR completely?

Does SSR hurt my SEO?

How do I know which strategy a page is using?

Wrapping Up

Useful Resources

Continue Learning

Step 1: Enable the `cacheComponents` Flag

Step 3: Remove `dynamic = 'force-dynamic'`

Step 4: Replace `dynamic = 'force-static'` with `'use cache'`

Step 5: Replace `revalidate` with `cacheLife`

Step 6: Delete `fetchCache`

Step 7: Move `fetch()` Cache Options into `'use cache'`

Step 8: Replace `unstable_cache` with `'use cache'`

Step 10: Delete `unstable_noStore`

Step 11: Fix `generateStaticParams`

`dynamicParams` is no longer supported

Await `params` inside `<Suspense>`, not at the top

Step 12: Wrap `cookies()`, `headers()`, and `searchParams` in `<Suspense>`

Step 13: Update `GET` Route Handlers

Step 14: Handle `generateMetadata` and `generateViewport`

Step 15: Remove `runtime = 'edge'`

What happens to my existing `fetch` cache and `unstable_cache` data during migration?

Why does my build fail on `new Date()` even with `instant = false` set?

Is `'use cache'` the same as the old `fetch` Data Cache?

My `revalidateTag(tag)` call now shows a TypeScript error — what changed?

Step 2: Mark cacheable parts with `"use cache"`