VENNStart
Guide

SSR, SSG and ISR in Next.js: what the build output tells you

How I tell static from dynamic App Router routes in the build output, separate data caching from page caching, and use revalidation in Next.js 15 and 16.

Lê Anh Tuấn5 min read

The App Router has no getStaticProps or getServerSideProps. Rendering depends on the APIs you call and the config across the route tree, and a page you thought was static can build as ƒ (Dynamic). Most of this applies to Next.js 15, or 16 without Cache Components. Cache Components get the last section.

The build output tells you static or dynamic

SSG is a route prerendered at build time, marked ○ (Static) or ● (SSG). ISR adds a revalidation rule to a prerendered route. Next.js serves the cached copy and regenerates it in the background, and the output gets a Revalidate column. SSR is now called dynamic rendering and shows as ƒ (Dynamic).

A route is static by default. It turns dynamic when any layout or page in it:

  1. Calls cookies(), headers(), or reads searchParams.
  2. Fetches with cache: 'no-store' or next: { revalidate: 0 }.
  3. Exports dynamic = 'force-dynamic' or revalidate = 0.

A param missing from generateStaticParams doesn't by itself make the whole route dynamic. With dynamicParams = true (the default), an otherwise static route can render and cache that path on its first request. With false, the path is a 404.

"fetch isn't cached by default" doesn't mean the page is always fresh. A plain fetch() in a route that doesn't call a request-time API runs once during next build. With no revalidate anywhere, the page stays that way until the next deploy.

Config in a shared layout cascades to every page below it. On a multilingual site, my locale layout had force-dynamic, and I later added revalidate = 3600 and generateStaticParams thinking that made it ISR. Every page still rendered per request. The fix was to drop dynamic and revalidate and keep only generateStaticParams.

In reverse, force-static makes cookies() and headers() come back empty and a logged-in user looks anonymous, as in a post about caching for logged-in users.

Per-user data stays out of the shared cache

The Data Cache stores fetch results with force-cache or next.revalidate, plus unstable_cache results. The Full Route Cache stores the HTML and RSC payload of static and ISR routes. A dynamic route can still read the Data Cache. This layout reads a cookie, so it's dynamic, yet the public nav comes from the cache:

// app/(shop)/layout.tsx (Next.js 15, or 16 without cacheComponents)
import { cookies } from 'next/headers'
import { unstable_cache } from 'next/cache'

const getPublicNav = unstable_cache(
  async () => (await fetch(`${API_URL}/navigation`)).json(),
  ['public-nav'],
  { revalidate: 3600, tags: ['navigation'] },
)

async function getViewer(token: string) {
  const res = await fetch(`${API_URL}/me`, {
    headers: { Authorization: `Bearer ${token}` },
    cache: 'no-store', // per-user: never in the shared cache
  })
  return res.ok ? res.json() : null
}

export default async function ShopLayout({ children }: { children: React.ReactNode }) {
  const token = (await cookies()).get('session')?.value // route becomes dynamic
  const nav = await getPublicNav() // same for everyone, served from cache
  const viewer = token ? await getViewer(token) : null
  return (
    <>
      <Header nav={nav} viewer={viewer} />
      {children}
    </>
  )
}

Every page below it becomes SSR. When most are public, I keep the layout static and load the user in a client component.

The worst mistake is a wrong cache key. unstable_cache builds its key from the function's arguments and keyParts, so a function that reads the token from a closure can serve one user's result to everyone. The fetch cache key includes request headers. That separates entries by token, but permissions can still go stale during the revalidation window. I keep authenticated requests out of force-cache.

SSG for content in the repo, ISR for a CMS

This blog is fully static. Every locale and slug pair comes from generateStaticParams, and dynamicParams = false makes unknown slugs 404. generateStaticParams has to return an array, even an empty one. If it returns nothing, the route is dynamic.

For content from a CMS or a database I use time-based ISR:

// app/products/[slug]/page.tsx (Next.js 15, or 16 without cacheComponents)
export const revalidate = 3600 // at most one regeneration per hour

export async function generateStaticParams() {
  const slugs = await getPopularProductSlugs(100) // build the popular ones only
  return slugs.map((slug) => ({ slug }))
  // dynamicParams defaults to true: other slugs render on first visit, then get cached
}

async function getProduct(slug: string) {
  const res = await fetch(`${API_URL}/products/${slug}`, {
    next: { revalidate: 3600, tags: ['products', `product:${slug}`] },
  })
  // Throwing keeps the last good page if a background regeneration fails
  if (!res.ok) throw new Error(`Product ${slug}: ${res.status}`)
  return res.json()
}

The first request after the hour gets the stale page and starts a regeneration. If that throws, Next.js keeps the last good version. getProduct throws for that reason instead of returning broken data.

A route uses the lowest revalidate across its layouts, page and fetches. A group layout set to 1800 under a root layout set to 3600 caps every page in the group at 30 minutes. The exported value has to be a literal: 600 works, 60 * 10 doesn't. Test caching with next build && next start, since next dev renders per request.

Conflicting options don't combine. A page exporting revalidate, generateStaticParams and force-dynamic together gets force-dynamic, and no ISR page is produced. I've made that mistake twice.

On-demand revalidation and the new signature in 16

For changes that show right after publishing, add on-demand revalidation. revalidatePath('/blog/my-post') refreshes one path, and a pattern needs the type, as in revalidatePath('/blog/[slug]', 'page'). revalidateTag('posts') refreshes every entry with that tag. When content shows up in several places, use tags, because revalidatePath('/blog') doesn't reach a homepage widget that fetched the same posts.

In Next.js 15, revalidateTag(tag) expires the entry immediately. In 16 the one-argument form is deprecated. revalidateTag(tag, 'max') serves stale data while it refreshes, and revalidateTag(tag, { expire: 0 }) expires it immediately, which the docs suggest for webhooks. updateTag(tag) only works inside Server Actions.

An open endpoint lets anyone flush your cache. Use POST, check a secret, and only accept known tags:

// app/api/revalidate/route.ts
import { timingSafeEqual } from 'node:crypto'
import { revalidatePath, revalidateTag } from 'next/cache'

const ALLOWED_TAGS = new Set(['posts', 'products', 'navigation'])

function isAuthorized(req: Request) {
  const given = Buffer.from(req.headers.get('x-revalidate-secret') ?? '')
  const expected = Buffer.from(process.env.REVALIDATE_SECRET ?? '')
  return expected.length > 0 && given.length === expected.length && timingSafeEqual(given, expected)
}

export async function POST(req: Request) {
  if (!isAuthorized(req)) return Response.json({ ok: false }, { status: 401 })

  const { tag, path } = (await req.json()) as { tag?: string; path?: string }
  if (tag && ALLOWED_TAGS.has(tag)) {
    revalidateTag(tag, { expire: 0 }) // Next.js 16; in 15: revalidateTag(tag)
    return Response.json({ ok: true, tag })
  }
  if (path?.startsWith('/')) {
    revalidatePath(path)
    return Response.json({ ok: true, path })
  }
  return Response.json({ ok: false }, { status: 400 })
}

If your CMS signs its payloads, verify them with its own helper. The CMS side is in connecting on-demand revalidation.

Tag drift fails silently. After a refactor, the menu cache was tagged seo-menu-data while the revalidation call still used menu-data, and Next.js said nothing. Keeping tag names in one shared constant prevents that. A module-level variable cache fails differently: the webhook only clears it in the process that got the request, and other instances keep the old copy.

Cache Components flip the defaults

Next.js 16 adds cacheComponents: true in next.config.ts. This site runs 16.2 without it, so this comes from the docs.

With it on, everything is dynamic, and you opt into caching with 'use cache' plus cacheLife and cacheTag. The dynamic, revalidate, fetchCache and dynamicParams options are gone. Anything reading cookies() or uncached data has to sit inside <Suspense>, or the build fails with "Uncached data was accessed outside of <Suspense>". A 'use cache' scope can't call cookies(), so you read it outside and pass it in as an argument.

I like that the public products go into the static shell while the per-user badge streams in separately:

import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { cacheLife, cacheTag } from 'next/cache'

async function getProducts() {
  'use cache'
  cacheLife('hours')
  cacheTag('products')
  return (await fetch(`${API_URL}/products`)).json()
}

async function ViewerBadge() {
  const token = (await cookies()).get('session')?.value
  if (!token) return <a href="/login">Sign in</a>
  const viewer = await getViewer(token) // uncached, streams in per request
  return <span>{viewer.name}</span>
}

export default async function Page() {
  const products = await getProducts() // cached, part of the static shell
  return (
    <>
      <Suspense fallback={<span className="badge-skeleton" />}>
        <ViewerBadge />
      </Suspense>
      <ProductGrid products={products} />
    </>
  )
}

I haven't turned it on, since most of the dynamicParams and revalidate config above would have to be rewritten. Until then, when I see ƒ where I expected ○, I check the shared layouts for cookies(), headers() or force-dynamic first.

  • Next.js
  • App Router
  • Caching
  • ISR
  • SSR
  • Performance

I'm Tuấn (Venn), a web developer in Ho Chi Minh City. I mostly build Next.js sites and web apps, and I take freelance work.

Work with me

More posts

  1. 01Guide4 min read

    Deploying Next.js and NestJS to AWS EC2 with Docker Compose

    How I deploy a pnpm monorepo to one EC2 box. Images get built in GitHub Actions and Docker Compose pulls them from GHCR. The server has no code.

  2. 02Guide4 min read

    How I store OAuth tokens for social media APIs in NestJS

    OAuth for Facebook, TikTok and YouTube in a NestJS API. State and PKCE, encrypted tokens, refreshing before each publish, and when to ask for a reconnect.

  3. 03vennee.dev3 min read

    llms.txt on my Next.js site, and now Lighthouse grades it

    vennee.dev has a hand-written llms.txt and an llms-full.txt built from the blog. Notes on the spec, .txt routes in Next.js, and Lighthouse 13's new audit.