DEV Community: Syed Muhammad Ali

Next.js Adoption Benchmark 2026: The Data

Syed Muhammad Ali — Sat, 05 Sep 2026 04:12:39 +0000

Ask ten developers whether Next.js is still "the safe choice" for a new project in 2026 and you'll get ten different, confidently-stated opinions. Half will point to X threads calling it bloated. The other half will point to the fact that it's still the framework every hiring manager's job post asks for. Neither side is usually backing it up with numbers.

So here's an attempt to actually back it up with numbers. This post pulls together public, verifiable data — npm download counts, GitHub star trends, and two of the most widely referenced annual developer surveys in the JavaScript/web ecosystem — into one place, so you can see what "adoption" for Next.js actually looks like right now, and how it's moved over the last two years, instead of guessing from vibes and Twitter screenshots.

This isn't a marketing deck and it isn't a hit piece. Every number below is cited, every source is linked, and where the data has real limitations (and it does), we say so instead of hiding it. By the end, you'll know exactly how Next.js's usage compares to Nuxt, Astro, and Remix/React Router, how developer sentiment toward it has actually shifted, and whether that shift should change what you reach for on your next project.

Why an Adoption Benchmark, Not Just Another "vs" Post

Most framework comparison posts are opinion pieces wearing a data costume — a table of checkmarks, a "winner" declared in the last paragraph, and zero sources you could go verify yourself. That's fine for a gut-check, but it's useless if you're trying to answer a real question like "is it still safe to bet a two-year SaaS roadmap on this framework."

An adoption benchmark is different. It doesn't ask "which framework is better" — that's subjective and depends entirely on your project. It asks a narrower, answerable question: how many developers are actually shipping with this framework right now, is that number growing or shrinking, and how do we know? Usage at scale is itself a signal — more usage generally means a bigger hiring pool, more Stack Overflow answers when something breaks, and a lower chance the framework gets abandoned mid-project. But a snapshot alone can't answer the "growing or shrinking" half of that — that needs a trend, which is exactly what most "adoption" posts skip.

Methodology: Where This Data Actually Comes From

Transparency matters more here than in a typical tutorial, so here's exactly what went into this benchmark:

npm download counts — pulled from npmtrends.com, which aggregates public npm registry download data, and cross-checked against independently published download figures from other analyses (cited inline below). This measures how many times npm recorded downloads of the package during the period, which is a proxy for active usage — an imperfect one, for reasons explained in the trend section below.
GitHub star counts — a slower-moving, harder-to-inflate signal of long-term community interest and visibility, pulled from the same npmtrends comparison pages, which surface live GitHub star counts alongside download data.
State of JS 2025 — the Devographics-run annual survey (closed November 2025, results published shortly after) that asks working developers what they actually use and how they feel about it.
Stack Overflow 2025 Developer Survey — the largest annual developer survey by respondent count, which tracks usage of web frameworks and technologies across the whole industry, not just the JavaScript ecosystem.

Every figure below is attributed to one of these four sources. Where a number comes from a third party's analysis of that data rather than the primary source itself, that's called out explicitly.

⚠️ Common Mistake (reading data like this): Treating npm download counts as a literal headcount of developers. A single CI pipeline that reinstalls dependencies on every commit can generate thousands of downloads a week on its own. Download counts are best read as a relative, noisy signal — how a framework compares to its direct competitors — not an absolute number of people using it. The section below goes into exactly how noisy.

Key Finding 1: Downloads and Stars — Next.js's Lead Is Still Large

Starting with a current snapshot before getting into the trend: weekly npm downloads and GitHub stars, compared across the major React and Vue meta-frameworks.

Framework	Weekly npm downloads (snapshot range)	GitHub stars
Next.js	~33–55 million, depending on the exact crawl (see note below)	~142,000
Astro	~4.5 million	~62,000
Nuxt	~1.8 million	~60,000

Source: npm package download statistics and GitHub repository data via npmtrends.com, snapshots taken across August 2026. Next.js's download figure is deliberately given as a range rather than one number — different snapshots of the same comparison page disagreed by tens of millions, which is exactly what "Key Finding 2" below digs into.

What this actually tells you: even at the low end of its range, Next.js is still roughly 7x Astro's weekly downloads and roughly 18x Nuxt's — an order-of-magnitude lead over its closest meta-framework competitors. That gap alone doesn't tell you Next.js is the better framework for your project (Astro is architecturally a better fit for a lot of content sites), but it does tell you the ecosystem, tooling, and hiring pool around Next.js are meaningfully larger right now.

Key Finding 2: Why This Post Doesn't Include a Multi-Year Download Chart

The rest of this post makes trend claims — Next.js "still" leading, its lead "isn't shrinking," Astro "gaining ground." Those are claims about direction over time, not a single point in time, so the obvious next step was to build a real Aug 2024 → Aug 2026 weekly-downloads chart to back them up properly. That turned into the most useful negative result in this whole benchmark: it isn't currently possible to build one from public data without presenting false precision, and it's worth explaining exactly why rather than shipping a chart that looks authoritative but isn't.

Two separate problems, found independently:

Problem 1 — no aggregator offers dated, independently-checkable historical data. npmtrends.com's comparison pages are live-only; there's no dated permalink that will still show August 2024's numbers when someone clicks it later. Any "historical" table built from what a search engine happened to have cached at some point isn't something a reader — or an editor fact-checking this post six months from now — can actually go verify. A citation that only worked at the moment the writer looked at it isn't a real citation.

Problem 2 — the underlying download numbers are themselves inconsistent, even within a single source. To find a workaround for Problem 1, we checked PkgPulse, a separate npm analytics site that explicitly claims to filter out CI/bot traffic. It didn't help — it made the case for caution stronger. Across three different PkgPulse pages, all published within about a month of each other in early 2026, Next.js's stated weekly downloads were reported as ~4.5 million, ~6.5 million, and ~39.6 million — an almost 9x spread from the same analytics provider, on pages published close together in time. That's on top of npmtrends' own comparison pages showing a roughly 33–55 million range for the same package across different crawls (see Key Finding 1's table above).

This lines up with what's independently documented about npm download data generally, not something specific to Next.js:

npm's own registry has recorded verified anomalies on its GitHub feedback tracker, including multi-day periods of zero recorded downloads for widely-used packages and sudden multi-week spikes with no corresponding release to explain them.
npmtrends.com's own client-side code contains a hard-coded outlier cap (publicly discovered by developers inspecting its bundle) that clamps any single day's download count above roughly 156,000 down to 70,000 before charting it — a tacit admission that raw registry numbers occasionally spike far beyond plausible organic usage.

What this means for the "trend" claims elsewhere in this post: they're supported by GitHub star growth and by two years of consistent survey results (State of JS has tracked Next.js as the dominant meta-framework in every recent edition, not just this one), not by a download-count time series — because no currently-available public source can responsibly produce one. Where this post says Next.js usage "isn't shrinking," that's a conclusion drawn from stars and surveys, and it's worth reading it that way rather than assuming a download chart backs it that we simply didn't show you.

⚠️ Why we didn't just publish one anyway: it would have been easy to pick one aggregator's numbers, round them into a clean-looking line chart, and move on — plenty of "original data" posts do exactly that. We're choosing not to, because a chart built on numbers this volatile would be worse than no chart: it would look more certain than the underlying data actually is, and a reader has no way to tell the difference between a rigorously-sourced chart and a plausible-looking one just by looking at it.

💡 Tip: If you need to make a real decision based on npm download trends — evaluating a dependency for your own team, for example — don't trust a single aggregator's absolute number, and be skeptical of a single aggregator's trend too. Cross-check at least two independent sources, and if they disagree by more than ~20–30%, treat the precise figures as unreliable and fall back on a more stable signal like GitHub stars or survey data.

Key Finding 3: Survey Usage Confirms the Same Pattern, From a Different Angle

Downloads and stars measure what gets installed. Surveys measure what developers say they actually reach for. It's worth checking both, because they can diverge — a framework can be widely installed as a transitive dependency without being anyone's first choice.

They don't diverge much here.

The Stack Overflow 2025 Developer Survey lists Next.js at roughly 20.8% usage among all respondents — developers across every stack, not just JavaScript. That places it as the fourth most-used technology in Stack Overflow's web frameworks and technologies question, behind only Node.js, React, and jQuery.
The State of JS 2025 survey — which only surveys people already working in the JavaScript ecosystem, so the base is narrower and the percentage naturally runs higher — puts Next.js usage at roughly 59% among respondents who answered the meta-framework question.

Two structurally different surveys, with different respondent pools and different questions, land on the same conclusion: Next.js remains the dominant choice among developers using JavaScript meta-frameworks.

💡 Tip: Notice these two numbers (20.8% and 59%) aren't contradictory even though they look wildly different — they're answering different questions. Stack Overflow asked a broad developer population which web frameworks and technologies they had worked with. State of JS asked "what do you use" only to people already building with JavaScript meta-frameworks. Always check what population a stat is drawn from before comparing two surveys directly.

Key Finding 4: Usage Is High, Satisfaction Is a Genuinely Mixed Story

This is the part that gets glossed over in most "Next.js is winning" posts, and it's the most interesting finding in this whole benchmark: usage and sentiment have clearly decoupled.

State of JS 2025 paints a much more mixed picture of Next.js sentiment. Next.js remains the dominant meta-framework at 58.6% usage, but its satisfaction score fell sharply—from 68% to 55%—the largest satisfaction decline highlighted in the survey. The project also generated the most comments overall, suggesting unusually strong polarization around the framework.

Recurring themes in the negative comments, based on the survey writeups referenced above, cluster around a few consistent complaints:

Perceived complexity growth — the jump from Pages Router to App Router, Server Components, and the caching model introduced genuinely more concepts to learn than the old getServerSideProps-era API surface.
Vercel-specific concerns — some respondents cited concerns around Vercel, deployment, and perceived platform lock-in, even though the framework itself remains open source and deployable elsewhere. See our breakdown of ISR/PPR support across hosting platforms if that's a concern for your own deployment target.
Migration fatigue — teams with large Pages Router codebases, moving to the App Router can represent a substantial architectural change rather than a simple version upgrade.

None of this means Next.js is declining in usage — the download and survey numbers above say the opposite. It means the "is Next.js good" conversation and the "is Next.js widely used" conversation are two separate questions with two separate answers, and it's worth keeping them separate in your own head when you're deciding what to build with.

Key Finding 5: Server Components Adoption Still Has Real Room to Grow

One more data point worth isolating on its own, since it's specific to the App Router rather than Next.js as a whole: independent industry analysis (cited via Netguru's 2025 React trends report) estimates that only around 29% of developers have actually used React Server Components in production, despite more than half expressing positive sentiment toward the underlying idea.

That's a meaningful gap between interest and adoption — and it lines up with what the App Router complexity criticism above would predict. A lot of developers are curious about Server Components conceptually, fewer have shipped something real with them yet. If you've been putting off learning the Server vs. Client Component split, you're statistically in the majority, not behind some curve everyone else has already cleared.

An Original Composite View: The DevStacked Adoption Index

Raw numbers from four different sources are hard to compare side by side, since they're measured on completely different scales (millions of downloads vs. a percentage vs. a star count). To make the picture easier to read at a glance, here's an original synthesis — not a new dataset, just a transparent way of putting the existing public numbers on the same footing. Because of the download volatility documented above, this index leans on the low end of each framework's observed download range rather than a single headline number.

Each framework is scored 0–100 on two axes, normalized against the highest value in this comparison set:

Install Share — weekly npm downloads (low end of the observed range), normalized against Next.js as the ceiling (Next.js = 100)
Star Share — GitHub stars, normalized against Next.js as the ceiling (Next.js = 100)

Framework	Install Share	Star Share
Next.js	100	100
Astro	~14	~44
Nuxt	~5	~43

How to read this table: Astro's Star Share is proportionally much closer to Next.js than its Install Share, indicating that its GitHub visibility and download footprint are less disproportionate than Next.js's. This is consistent with Astro's growing visibility, but the ratio itself should not be interpreted as a measure of production adoption.

⚠️ This index is illustrative, not scientific. It's a normalized view of two public metrics, built to make comparison easier — it isn't a peer-reviewed methodology, and it deliberately leaves out factors like job postings, Discord activity, or bundle size that a more rigorous study would weigh in. Treat it as a visualization aid on top of the cited numbers above, not a standalone data source of its own.

What This Actually Means If You're Choosing a Framework Right Now

Numbers are only useful if they change a decision. Here's the practical read:

If you're optimizing for hiring, ecosystem depth, and "will this still be maintained in three years" — Next.js's install base, download volume, and star trend are all large and stable-to-growing enough that this risk is close to zero right now, sentiment complaints notwithstanding.
If your project is content-heavy (marketing site, docs, blog) and doesn't need much client-side interactivity — Astro's content-focused architecture and growing adoption make it worth evaluating instead of defaulting to Next.js out of habit. See our full framework rendering strategies breakdown to understand where Next.js's SSR/SSG/ISR model genuinely earns its complexity versus where it's overkill.
If your team is Vue-first — Nuxt's numbers are smaller in absolute terms, but that's expected given Vue's smaller overall footprint versus React; within the Vue ecosystem specifically, Nuxt is the dominant meta-framework choice.
If the App Router's complexity is your specific hesitation — that concern shows up clearly in the sentiment data, and it's legitimate. The fix isn't necessarily switching frameworks; it's learning the caching model deliberately instead of picking it up by trial and error. Our Cache Components migration guide exists specifically because the App Router's caching model is one of the areas that often requires deliberate learning.

Limitations of This Benchmark

Being upfront about what this data can't tell you:

npm downloads don't equal production traffic, and — as shown above — different aggregators can disagree by several times over for the same package. Treat any single download figure, including the ones in this post, as directional rather than precise.
Survey respondents self-select. People who fill out the State of JS survey are, by definition, developers engaged enough with the JS community to know the survey exists — that skews toward more opinionated, more online developers than the average working programmer.
This post deliberately does not include a multi-year download chart, for the reasons explained in Key Finding 2. Every public npm download aggregator checked for this benchmark — including two independent ones cross-checked against each other — disagreed with itself or with the other source by several times over. Trend claims in this post lean on GitHub stars and multi-year survey results instead, which are more stable but say less about raw download volume.
"Usage" and "primary framework" aren't the same thing. Some respondents counted in these numbers might use Next.js at work but prefer something else for side projects, or vice versa. Surveys capture usage, not necessarily preference.

Frequently Asked Questions

Is Next.js actually declining in popularity in 2026?

No — the download, GitHub star, and survey data above all show Next.js with a commanding lead over its direct competitors, and none of the trend indicators checked here show that lead shrinking. What's changed is that criticism of its complexity has become more visible and vocal, which can feel like decline on social media even when the underlying usage numbers don't show one.

Why do npm download numbers for Next.js vary so much between sources?

npm download counts are known to include a large, variable share of automated traffic — CI pipelines, monorepo tooling, and infrastructure that reinstalls dependencies on every run — and different aggregators crawl and process the registry at different times and with different outlier handling. This is a documented issue across the npm ecosystem, not something specific to Next.js. GitHub stars and survey data are more stable signals for tracking direction over time.

Why do Stack Overflow and State of JS report such different usage percentages for Next.js?

They're surveying different populations. Stack Overflow surveys developers across every language and stack, so Next.js's 20.8% is a share of a much larger, more general pool. State of JS only surveys people already working in the JavaScript ecosystem, so its 59% figure is a share of a smaller, more specialized pool. Both can be accurate at the same time.

Should low satisfaction scores stop me from choosing Next.js for a new project?

Not on their own. Sentiment data reflects real, legitimate complaints — mostly around App Router complexity — but usage and satisfaction are separate metrics here, and Next.js's usage hasn't followed its satisfaction score downward. Weigh the specific complaints (are you worried about caching complexity? Vercel lock-in? migration cost?) against whether they actually apply to your project, rather than treating the satisfaction number alone as a verdict.

Is Astro a real threat to Next.js's dominance?

For a specific category of projects — content-heavy sites with light interactivity — yes, and the combination of faster relative download growth, a star-to-download ratio ahead of Next.js's, and strong State of JS satisfaction scores suggests Astro deserves serious attention for that use case. For interactive, data-heavy applications (dashboards, SaaS products, anything with complex client state), Astro isn't really competing in the same category as Next.js in the first place.

How often should a benchmark like this be updated?

Every 6–12 months is reasonable for framework adoption data — meaningful shifts in download trends or survey sentiment take real time to show up, and updating more frequently mostly just captures noise (see the download-volatility discussion above). Major version releases (like a future Next.js 17) or a new annual State of JS/Stack Overflow survey are natural triggers to refresh a benchmark like this one.

Wrapping Up

The honest takeaway from all of this: Next.js's adoption lead in 2026 is not in question, and it hasn't shrunk over the last two years by any indicator checked here — it's still the default choice for the majority of developers picking a React meta-framework, by a wide margin over Astro, Nuxt, and Remix/React Router combined. What is legitimately in question is whether that adoption reflects enthusiasm or inertia, and the sentiment data — a real, measured satisfaction drop alongside unchanged usage dominance — suggests it's genuinely a mix of both. That's a more useful, more honest answer than either the "Next.js is dying" hot takes or the "just use Next.js, no debate" defaults you'll see argued with equal confidence and zero sources.

If the App Router's caching model is the specific thing holding you back from feeling confident in this stack, that's a solvable, learnable problem rather than a reason to abandon ship — start with this Next.js 16 Cache Components guide.

Continue Learning

Sources

Next.js Cache Components Migration Guide (2026)

Syed Muhammad Ali — Mon, 31 Aug 2026 03:12:28 +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

What Is Authentication? A Beginner's Guide (2026)

Syed Muhammad Ali — Sun, 30 Aug 2026 11:18:03 +0000

Every time you type your email and password into a login form, something is quietly deciding whether you actually get in. That decision — proving you are who you say you are — is called authentication, and it's one of those concepts every developer touches constantly but rarely stops to explain from scratch.

If you've ever wondered what actually happens between "click Sign In" and "welcome back," or mixed up authentication with authorization in an interview, this guide is for you. By the end, you'll know exactly what authentication is, how the major methods work under the hood, and how to build a basic authentication flow yourself.

What Is Authentication? (Quick Answer)

Authentication is the process of verifying that someone is who they claim to be. It answers one question: "Who are you?" This usually happens by checking a password, a code from your phone, a fingerprint, or a token — something only the real user should have or know.

Authentication is different from authorization, which answers a separate question: "What are you allowed to do?" A logged-in user is authenticated. Whether that user can delete another person's account is authorization. Mixing these two up is one of the most common beginner mistakes — keep them mentally separate from the start.

💡 Simple way to remember it: Authentication = ID check at the door. Authorization = the guest list that decides which rooms you can enter once you're inside.

Why Authentication Matters

Without proper authentication and authorization, an app that stores personal data could expose private information to unauthorized users. Authentication provides the identity context that many authorization, personalization, and auditing systems rely on.

It matters for a few concrete reasons:

Privacy — only the right person sees their own data
Security — prevents account takeover and unauthorized access
Personalization — apps can remember who you are across visits
Accountability — actions can be traced back to a real identity (important for admin tools, financial apps, audit logs)

Authentication vs. Authorization: The Difference That Trips Everyone Up

	Authentication	Authorization
Question it answers	Who are you?	What can you do?
Happens	First	After authentication
Example	Logging in with a password	Only admins can access `/admin`
Failure result	401 Unauthorized	403 Forbidden

Why the HTTP status codes are confusingly named: 401 Unauthorized actually means "you're not authenticated" (log in first), while 403 Forbidden means "you're authenticated, but not allowed to do this." Yes, 401 should really be called "Unauthenticated" — it's a long-standing naming quirk in the HTTP spec that trips up almost every developer at least once.

Related: Role-Based Access Control (RBAC) in Next.js 16 goes deep on the authorization half of this once you're ready for it.

How Authentication Works (Step by Step)

At a high level, almost every authentication system follows the same basic loop:

The user provides credentials — a password, a fingerprint, a one-time code, or an existing account from another provider (like signing in with Google)
The server verifies those credentials — checking a hashed password, validating a signed token, or confirming a biometric match
The server issues proof of identity — usually a session or a token, stored in a cookie or sent back to the client
That proof is sent with future requests — so the user doesn't have to log in again on every page

User submits credentials
        ↓
Server verifies credentials
        ↓
Server issues session/token
        ↓
Client stores it (cookie)
        ↓
Future requests include it
        ↓
Server verifies it's still valid

That last step — verifying the proof of identity on every request — is what keeps a user "logged in" without asking for their password on every single page.

The Main Types of Authentication

There isn't just one way to authenticate someone. Here are the methods you'll actually run into as a developer.

1. Password-Based Authentication

The classic: a username/email plus a password, checked against a hashed value stored in your database. Never store plain-text passwords — always hash them with a slow, password-specific hashing algorithm such as Argon2id. If it's not available, bcrypt or another appropriate password hashing algorithm can be used.

// lib/auth/hash-password.ts
import bcrypt from "bcryptjs";

const SALT_ROUNDS = 12;

export async function hashPassword(plainPassword: string): Promise<string> {
  return bcrypt.hash(plainPassword, SALT_ROUNDS);
}

export async function verifyPassword(
  plainPassword: string,
  hashedPassword: string
): Promise<boolean> {
  return bcrypt.compare(plainPassword, hashedPassword);
}

What's happening here: bcrypt.hash() doesn't just scramble the password — it applies a slow, computationally expensive algorithm on purpose, which increases the cost of each password guess and makes large-scale brute-force attacks significantly more expensive. SALT_ROUNDS = 12 is above OWASP's minimum bcrypt work factor of 10, but the right value depends on your server's hardware and traffic. Benchmark your production environment and choose a cost that makes password verification sufficiently expensive without creating unacceptable latency.

⚠️ bcrypt limitation: bcrypt has a hard 72-byte input limit, and most implementations (including bcryptjs) silently truncate anything past it rather than erroring. Because UTF-8 characters like emoji or accented letters can take up to 4 bytes each, a password that looks well under the limit in characters can still get silently cut short in bytes — which can cause two different passwords to be treated as equivalent after truncation.

OWASP currently recommends enforcing a maximum of 72 bytes (or less, depending on the implementation) when bcrypt is used. Because UTF-8 characters can occupy multiple bytes, a character-count limit alone doesn't necessarily correspond to bcrypt's byte limit.

⚠️ Common Mistake: Comparing passwords with a plain === check after "encrypting" them with something reversible like Base64. That's encoding, not hashing — it can be reversed instantly. Only use a dedicated password-hashing library.

2. Session-Based Authentication

After a successful login, the server creates a session record stored in server-side session storage such as a database or shared cache — and gives the browser a random session ID in an httpOnly cookie. On every request, the server looks up that ID to know who's logged in.

// lib/auth/session.ts
import { cookies } from "next/headers";
import { randomUUID } from "crypto";

export async function createSession(userId: string, expiresAt: Date) {
  // Generate a random, unguessable session ID — never store the raw
  // userId (or anything else predictable) directly as the cookie's
  // value. The cookie is a reference you look up server-side; it
  // should never double as proof of identity on its own.
  const sessionId = randomUUID();

  // Persist the mapping server-side, e.g.:
  // await db.session.create({ data: { sessionId, userId, expiresAt } });

  const cookieStore = await cookies();

  cookieStore.set("session_id", sessionId, {
    httpOnly: true,
    secure: true,
    sameSite: "lax",
    expires: expiresAt,
    path: "/",
  });
}

Why each flag matters: httpOnly stops client-side JavaScript from reading the cookie (blocking a common XSS attack path). secure means it's only sent over HTTPS. sameSite: "lax" limits when the browser sends the cookie in cross-site requests and provides some CSRF protection. For state-changing operations, you should still implement an appropriate CSRF defense rather than relying on SameSite alone.

Pros: straightforward server-side revocation; deleting a session record can invalidate that session immediately, and deleting all of a user's sessions can log them out everywhere.

Cons: can require a server-side session lookup on authenticated requests, although caching can reduce the cost.

3. Token-Based Authentication (JWT)

Instead of looking anything up server-side, a JSON Web Token (JWT) packs the user's identity directly into a signed token. In a stateless JWT design, the server can verify the token cryptographically without looking up a session record in the database.

// lib/auth/jwt.ts
import { SignJWT, jwtVerify } from "jose";

const secretKey = new TextEncoder().encode(process.env.AUTH_SECRET);

export async function signToken(userId: string, expiresAt: Date) {
  return new SignJWT({})
    .setProtectedHeader({ alg: "HS256" })
    .setSubject(userId)
    .setIssuedAt()
    .setExpirationTime(expiresAt)
    .sign(secretKey);
}

export async function verifyToken(token: string) {
  try {
    const { payload } = await jwtVerify(token, secretKey, {
      algorithms: ["HS256"],
    });
    return payload;
  } catch {
    return null; // invalid or expired
  }
}

What's happening here: jose is the standard, actively maintained library for signing and verifying JWTs using the Web Crypto API — it works in Node.js, edge runtimes, and browsers. setSubject(userId) stores the user's ID in the token's standard sub claim. jwtVerify() automatically rejects the token if the signature doesn't match or if it's expired, so you never write manual expiry checks.

⚠️ Signing is not encryption. A JWT's payload is only base64url-encoded, not encrypted — anyone can decode and read it. The signature only proves it wasn't tampered with. Never put sensitive data (passwords, secrets) inside a JWT payload.

Pros: no database lookup needed to verify identity, works well across distributed/stateless servers.

Cons: harder to instantly revoke a single token before it expires (it's valid until it naturally expires unless you build extra machinery around it).

💡 For a deeper side-by-side of these two models — including how each behaves at scale — see Session vs JWT: Which Should You Use in Next.js 16?

4. OAuth / OpenID Connect (Social Login)

OAuth 2.0 is an authorization framework that lets an application obtain limited access to resources on behalf of a user. It doesn't, by itself, define how an application verifies the user's identity.

For "Sign in with Google," "Sign in with Microsoft," and similar login flows, applications commonly use OpenID Connect (OIDC) — an identity layer built on top of OAuth 2.0. The identity provider authenticates the user and returns an ID token containing claims about that authentication.

User clicks "Sign in with GitHub"
        ↓
Redirected to GitHub
        ↓
User authenticates and approves access
        ↓
GitHub redirects back with a code
        ↓
Your server exchanges the code for tokens
        ↓
Your server validates the OIDC identity information
        ↓
Your app creates its own session

This is why OAuth is so popular for beginners and production apps alike — you outsource the hardest parts (password storage, breach risk, 2FA) to a provider that already does it well.

5. Multi-Factor Authentication (MFA / 2FA)

MFA requires more than one proof of identity — typically "something you know" (a password) plus "something you have" (a phone, an authenticator app code, a hardware key). Even if a password leaks, the attacker still can't get in without the second factor.

6. Passwordless Authentication (Magic Links & Passkeys)

Two increasingly common alternatives to passwords:

Magic links — the user enters their email, gets a one-time sign-in link, and clicking it logs them in. No password to remember or leak.
Passkeys (WebAuthn) — device-based authentication using Face ID, Windows Hello, or a hardware security key. No shared secret exists to steal in the first place, which makes passkeys resistant to phishing in a way passwords fundamentally aren't.

A Minimal Authentication Flow in Next.js

Here's a simplified but realistic login flow using Next.js 16, TypeScript, and session cookies — the same core pattern used by most production apps, just without the database wiring.

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

import { redirect } from "next/navigation";
import { verifyPassword } from "@/lib/auth/hash-password";
import { createSession } from "@/lib/auth/session";
import { z } from "zod";

const loginSchema = z.object({
  email: z.email(),
  password: z.string().min(8),
});

export async function login(prevState: unknown, formData: FormData) {
  const parsed = loginSchema.safeParse({
    email: formData.get("email"),
    password: formData.get("password"),
  });

  if (!parsed.success) {
    return { error: "Enter a valid email and password." };
  }

  // Look up the user in your database (pseudocode)
  const user = await db.user.findUnique({ where: { email: parsed.data.email } });

  if (!user || !(await verifyPassword(parsed.data.password, user.passwordHash))) {
    // Same generic error for both cases — don't reveal which one was wrong
    return { error: "Invalid email or password." };
  }

  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000); // 7 days
  await createSession(user.id, expiresAt);

  redirect("/dashboard");
}

What's happening here: the form data is validated with Zod before touching the database — never trust raw input. Notice the login failure returns the same generic message whether the email doesn't exist or the password is wrong; revealing which one failed makes it easier for attackers to enumerate valid accounts. A working session gets created only after the password check succeeds, then the user is redirected.

⚠️ Common Mistake: Checking authentication only in proxy and assuming that's enough. Proxy-level checks are a good UX shortcut (fast redirect before a page even loads), but sensitive Server Actions, Route Handlers, and data-access functions should independently verify authentication and authorization rather than relying solely on proxy.ts.

Building this by hand is a great way to learn, but most production apps reach for a maintained library instead — see How to Add Auth.js (NextAuth v5) in Next.js 16, Add Clerk Authentication to Next.js 16, or (if you're already on Supabase) Supabase Auth vs Firebase Auth.

Common Authentication Mistakes to Avoid

Storing plain-text passwords — always hash with Argon2id or bcrypt, never store or log the raw password
Storing a predictable value as the session cookie — the cookie should be a random, unguessable reference, never the raw user ID or anything else an attacker could construct
Weak or reused session/JWT secrets — generate a long, random secret and never commit it to git
Revealing which field was wrong — "Invalid email" vs. "Invalid password" tells attackers an account exists
Skipping rate limiting — without it, attackers can brute-force passwords with unlimited attempts
Relying only on client-side checks — a hidden button or disabled form field doesn't stop a direct API request
Forgetting to expire sessions/tokens — every session and token should have a sane expiry, not live forever

Frequently Asked Questions

What is the difference between authentication and authorization?

Authentication confirms who someone is (logging in). Authorization decides what they're allowed to do once they're recognized (permissions, roles, access control). You always need authentication before authorization can happen.

Is a login system the same thing as authentication?

Yes — a login system is simply the implementation of authentication. Whatever mechanism confirms a user's identity (password, OAuth, passkey) is functioning as authentication, regardless of what you call the feature.

What's the difference between sessions and JWTs?

A session stores authentication/session state on the server and gives the browser only a random reference ID, which allows instant revocation. A JWT stores the identity data directly inside a signed token the server can verify without a database lookup, trading easy revocation for less server-side state.

Keep JWT minimal — a JWT should not be treated as a general-purpose user profile or database replacement.

Do I need a library to build authentication, or can I build it myself?

You can build basic password + session authentication yourself using the patterns above, but for anything production-facing, an established library (Auth.js, Clerk, Better Auth, or your database provider's built-in auth) is strongly recommended — they handle edge cases like token rotation, breach detection, and secure defaults that are easy to get subtly wrong by hand.

Is two-factor authentication (2FA) actually necessary?

For anything holding sensitive data — financial info, personal messages, admin access — yes. 2FA dramatically reduces account takeover risk even when a password leaks, since the attacker also needs the second factor.

Are passkeys better than passwords?

Generally yes, from a security standpoint — passkeys are phishing-resistant because there's no shared secret to trick someone into revealing. Adoption is still growing, though, so most apps currently offer passkeys as an option alongside passwords rather than a full replacement.

Wrapping Up

Authentication boils down to one question — "who are you?" — answered through a password, a token, a device, or some combination of them. Once you separate authentication from authorization, the ecosystem becomes easier to understand: passwords and passkeys are authentication mechanisms, sessions and JWTs are ways to maintain authenticated state, and OAuth/OIDC provide delegated authorization and federated identity.

If you're building this in a real Next.js app, the next logical steps are wiring up role-based authorization on top of your authentication layer, and deciding between session-based and JWT-based auth based on whether instant revocation matters for your product.

Continue Learning

Free Developer Tools

Zod Schema Generator — generate a validated schema for your role/permission payloads straight from a JSON sample or TypeScript interface, including a ready-to-use Server Action.
Supabase RLS Policy Generator — pair this guide's application-level RBAC with database-level Row Level Security. Generates owner-only, team, and admin-override policies with the auth.uid() performance wrapper built in.

S3 vs Supabase Storage vs Cloudinary (2026 Guide)

Syed Muhammad Ali — Sat, 29 Aug 2026 06:12:24 +0000

You're building a Next.js app that needs to store files — user avatars, product photos, PDFs, whatever — and you hit the same wall every developer hits: where do the actual files go?

For most apps, storing large user-uploaded files directly in Postgres isn't the best fit. Object storage is designed for this workload and keeps your database focused on relational data. So you're left picking between three names that show up in almost every tutorial: AWS S3, Supabase Storage, and Cloudinary. They all "store files," but they solve genuinely different problems, and picking the wrong one means either fighting your tools for months or paying for features you'll never touch.

By the end of this guide, you'll know exactly what each one is actually built for, how to wire up a basic upload with real code for all three, what they cost, and which one fits your specific project — not just whichever one showed up first in your search results.

Quick Answer

Choose AWS S3 if you want inexpensive, highly flexible object storage with a huge ecosystem and full AWS control.
Choose Supabase Storage if you're already using Supabase for your database and auth — it plugs directly into the same Row Level Security model you already know.
Choose Cloudinary if images and videos are a core part of your product and you want transformations (resizing, cropping, format conversion, transcoding) handled automatically, with almost no backend code.

If none of those single-sentence answers settled it, keep reading — the "why" behind each one is where the real decision lives.

Why This Comparison Is Tricky

Most "S3 vs X" posts compare feature checklists side by side and call it a day. The problem is these three tools aren't really competing for the same job:

S3 is raw object storage. It stores bytes under a key. It has no idea what an "image" is — resizing, format conversion, and CDN delivery are all things you have to bolt on separately (usually CloudFront).
Supabase Storage is an object-storage service with an S3-compatible API, wrapped in Supabase's API, authentication, and Postgres RLS model.
Cloudinary is a media pipeline first, storage second. Its actual product is on-the-fly image and video transformation — resize, crop, convert to WebP/AVIF, transcode video, remove backgrounds — all driven by URL parameters, with storage as the thing that makes that possible.

Keep that distinction in mind through the rest of this guide: you're not just picking "where files live," you're picking how much of the surrounding work (delivery, optimization, access control) you want to own yourself.

At a Glance

	AWS S3	Supabase Storage	Cloudinary
What it actually is	Raw object storage	Object storage + Supabase Auth/RLS integration	Media transformation pipeline
Access control model	IAM policies + bucket policies	Row Level Security (SQL policies)	Signed uploads / upload presets
Built-in image transforms	None — add an image-processing/optimization layer separately	Available in Paid Plans	Extensive (resize, crop, AI background removal, format negotiation)
Video handling	None — you'd wire up a separate transcoding service	Not a core feature	First-class — transcoding, adaptive streaming, a built-in video player
CDN included	No — add CloudFront separately	Yes, via the Supabase CDN	Yes, built in
Best paired with	Any stack, especially if you already use AWS	A Supabase-backed app (Postgres + Auth)	Any stack where images/video are core UX
Free tier	12-month intro tier only, otherwise pay-as-you-go	~1 GB storage, 5 GB egress (check current limits)	25 credits/month (1 credit = 1 GB storage, 1 GB bandwidth, or 1K transformations) credits are shared across these resources
Pricing model	Storage + requests + data transfer, billed separately (see below)	Flat plan tiers + usage overages	Credit-based, fixed tiers

💡 Tip: Pricing on all three changes often enough that any number printed in a blog post is a snapshot, not a promise. Treat the figures above as ballpark, and always check each provider's live pricing page before committing budget to one.

AWS S3: Raw, Cheap, and You Own Everything

Amazon S3 (Simple Storage Service) is the original cloud object store — files go in under a "key" (basically a path string), and you get them back out the same way. No opinions about what the file is.

Where S3 wins:

One of the cheapest raw storage per GB at real scale, especially once you're past a few hundred GB
Full control — bucket policies, lifecycle rules (auto-delete or archive old files), versioning, cross-region replication
The de facto standard — every CDN, backup tool, and CMS speaks S3's API, including S3-compatible alternatives like Cloudflare R2 and Backblaze B2

Where S3 struggles:

Zero built-in image processing. Want a thumbnail? You'll need a separate image-processing layer, such as a Lambda-based workflow, an image optimization service, or a framework-level optimizer.
No CDN out of the box — S3 alone serves from one region. You need CloudFront (or another CDN) in front of it for real-world performance.
More setup: IAM users, bucket policies, CORS config, and (for direct browser uploads) presigned URLs are all things you configure by hand.

S3 Pricing Is More Than "Per GB Stored"

This matters enough for a "which is cheapest" comparison that it deserves its own callout: S3's bill is not just storage. You're billed separately for several things at once:

Storage — per GB-month, and it varies by storage class (Standard, Infrequent Access, Glacier, etc.)
Requests — PUT/COPY/POST/LIST requests cost more per-request than GET requests, and both are metered
Data transfer out — serving files to the internet (not through a CDN) is billed per GB and is usually the line item that surprises people
Retrieval fees — if you move infrequently-accessed files to a cheaper storage class, pulling them back out costs extra
Lifecycle transitions — moving objects between storage classes automatically (e.g. Standard → Glacier after 90 days) also incurs a small per-object request cost

A storage-only comparison (S3 vs. Supabase's per-GB rate vs. Cloudinary's credits) misses this. An app that serves thumbnails directly from S3 with heavy traffic and no CDN in front can rack up request and transfer charges that dwarf the storage bill itself — which is exactly why pairing S3 with CloudFront isn't just a performance decision, it's often a cost one too (CloudFront's cached data transfer is typically cheaper than S3's direct transfer-out rate).

A Minimal S3 Upload in Next.js 16

This uses the presigned URL pattern — your server never touches the file bytes, it just asks S3 for permission and hands the browser a temporary signed URL to upload directly.

npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

// lib/s3-client.ts
import { S3Client } from "@aws-sdk/client-s3";

export const s3Client = new S3Client({
  region: process.env.AWS_REGION!,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
});

// app/api/presigned-url/route.ts
import { NextRequest, NextResponse } from "next/server";
import { PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { s3Client } from "@/lib/s3-client";
import { randomUUID } from "crypto";
import { auth } from "@/lib/auth"; // your auth solution of choice

const ALLOWED_TYPES = ["image/jpeg", "image/png", "image/webp"];
const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB

export async function POST(request: NextRequest) {
  // 1. Authentication — reject anonymous requests before doing anything else
  const session = await auth();
  if (!session?.user) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { fileName, fileType, fileSize } = await request.json();

  // 2. MIME allowlist — reject anything you don't explicitly support
  if (!ALLOWED_TYPES.includes(fileType)) {
    return NextResponse.json({ error: "Unsupported file type" }, { status: 400 });
  }

  // 3. Max file size — a best-effort check against the size the client reports.
  // A presigned PUT can't fully enforce this on its own; see the note below.
  if (typeof fileSize !== "number" || fileSize > MAX_FILE_SIZE) {
    return NextResponse.json({ error: "File too large" }, { status: 400 });
  }

  // 4. Filename sanitization — never trust the client's filename for anything
  // beyond picking a safe extension. Strip everything else.
  const safeExtension =
    fileName?.split(".").pop()?.replace(/[^a-z0-9]/gi, "").slice(0, 10) || "bin";

  // 5. Server-generated key — the client never chooses where its file lands.
  // Scoping by the authenticated user's id is also your authorization boundary:
  // even if someone tampers with the request, they can only ever get a
  // presigned URL scoped to their own prefix.
  const key = `uploads/${session.user.id}/${randomUUID()}.${safeExtension}`;

  const command = new PutObjectCommand({
    Bucket: process.env.S3_BUCKET_NAME!,
    Key: key,
    ContentType: fileType,
  });

  const uploadUrl = await getSignedUrl(s3Client, command, { expiresIn: 60 });

  return NextResponse.json({ uploadUrl, key });
}

What's happening here: your server never sees the file bytes — it just signs a temporary permission slip — but it does gate who gets that slip (authentication), what they're allowed to upload (MIME allowlist), roughly how big it can be, and exactly where it lands (a server-generated key under the caller's own user id, never a client-supplied path). The browser then does a plain fetch(uploadUrl, { method: "PUT", body: file }) straight to S3, keeping large files off your server entirely — which matters a lot on serverless platforms with body-size limits.

⚠️ This example is still a demonstration, not a drop-in production upload endpoint. A few things it deliberately leaves out, worth knowing about before you ship:

Authoritative size enforcement — the fileSize check above only validates what the client claims its file is. A presigned PutObjectCommand doesn't enforce a byte limit by itself. For a hard limit, use a presigned POST with a content-length-range condition instead of a presigned PUT, or verify the object's real size after upload (via an S3 event notification or a scheduled cleanup job) and delete anything oversized.

Checksum/content validation — for anything security-sensitive, pass a ChecksumSHA256 to PutObjectCommand so S3 rejects an upload whose bytes don't match what the client claimed, and consider scanning uploaded files (e.g. with a virus-scanning Lambda trigger) before treating them as safe to serve.

Rate limiting — nothing above stops one authenticated user from requesting thousands of presigned URLs per minute. Put a rate limiter (Upstash Ratelimit, a simple sliding-window check in your database, or your edge/CDN's built-in limiting) in front of this route in production.

⚠️ Common Mistake: Making the bucket public "to make things easier." None of the common upload/display patterns need a public bucket — presigned URLs grant scoped, temporary access without exposing the bucket itself. Leave Block all public access on unless you have a specific, narrow reason to open one prefix.

Supabase Storage: S3 Underneath, Postgres on Top

Supabase Storage provides an S3-compatible object-storage interface and integrates it with Supabase Auth and Postgres RLS — every bucket can be protected by Row Level Security policies, the same SQL-based authorization system you're already using for your database tables if you're on Supabase.

Where Supabase Storage wins:

If you're already using Supabase Auth + Postgres, storage access rules live in the same mental model — a policy like "a user can only read their own files" is one create policy statement, not a separate IAM configuration
Simple, batteries-included API (upload, download, createSignedUrl) that works identically from the browser or the server
Offers on-the-fly image transformations included via a query-param API, so you don't always need a separate CDN layer for simple resizing, although availability and usage depend on your plan

Where Supabase Storage struggles:

Currently supports automatic WebP optimization but its transformation system is considerably narrower than Cloudinary's
Free-tier storage and egress are modest — fine for an MVP, tight for a media-heavy app
You're tied to Supabase's infrastructure choices; less low-level control than raw S3

A Minimal Supabase Storage Upload

npm install @supabase/supabase-js @supabase/ssr

// lib/supabase/client.ts
import { createBrowserClient } from "@supabase/ssr";

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!
  );
}

// components/avatar-uploader.tsx
"use client";

import { createClient } from "@/lib/supabase/client";

export function AvatarUploader() {
  const supabase = createClient();

  const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    // Get the current user from the session — never take a userId as a
    // prop or form value. The path below is only as trustworthy as this.
    const {
      data: { user },
    } = await supabase.auth.getUser();

    if (!user) return;

    const filePath = `${user.id}/${Date.now()}-${file.name}`;

    const { error } = await supabase.storage
      .from("avatars")
      .upload(filePath, file, { upsert: false });

    if (error) {
      console.error("Upload failed:", error.message);
      return;
    }

    // For a private bucket, generate a temporary signed URL to display it
    const { data: signed } = await supabase.storage
      .from("avatars")
      .createSignedUrl(filePath, 60 * 60); // 1 hour

    console.log("Signed URL:", signed?.signedUrl);
  };

  return <input type="file" accept="image/*" onChange={handleUpload} />;
}

What's happening here: .storage.from("avatars").upload(...) uploads directly through the Supabase client — no separate presigned-URL round trip needed, because auth and authorization already ride along with the client's session. createSignedUrl mirrors S3's presigned-URL pattern, but scoped through the bucket's own RLS policies instead of IAM.

-- Only let a user manage files inside their own folder
create policy "Users can upload their own avatar"
on storage.objects
for insert
to authenticated
with check (
  bucket_id = 'avatars'
  and (select auth.uid())::text = (storage.foldername(name))[1]
);

What's happening here: storage.foldername(name) splits the object path (e.g. user-id/photo.jpg) into segments, so this policy checks that the folder name matches the uploader's own auth.uid(). The authorization model uses Postgres RLS, just like your database tables.

⚠️ Important — don't mistake a client-supplied path for real security. In the component above, user.id comes from supabase.auth.getUser(), which reads the server-verified session — that part is trustworthy. But the resulting filePath string is still just something the client constructs and sends along with the upload request. What actually makes this safe is the RLS policy, which independently re-checks (select auth.uid()) against the path on Supabase's side, every time, regardless of what the client sends.

This distinction matters: if you ever accept a user id as a raw prop, a hidden form field, or anything else that isn't derived from the verified session — or if RLS on the bucket is ever disabled or misconfigured — nothing stops a client from writing someone-elses-id/file.jpg into the path and having the request succeed. The policy is the actual security boundary here, not the fact that the code "usually" builds the path from the right value.

💡 Tip: Writing RLS policies by hand for every bucket pattern (owner-only, team-shared, admin override) gets repetitive fast. If you're already on Supabase, a Supabase RLS Policy Generator can produce the strict, performance-optimized version of these policies — including the (select auth.uid()) wrapper used above — for your specific access pattern.

Cloudinary: A Media Pipeline for Images and Video

Cloudinary's whole pitch is different from the other two: you're not really buying storage, you're buying transformation-on-delivery — and it's easy to think of Cloudinary as "an image tool," but that undersells it. Video is a first-class part of the product too: transcoding, adaptive bitrate streaming, and a dedicated video player component (CldVideoPlayer) ship alongside the image tooling, not as an afterthought. Upload one asset once, and every size, crop, and format you'll ever need — image or video — gets generated from URL parameters, with no separate resize job and no manual WebP conversion.

Where Cloudinary wins:

Transformations are wildly capable across both media types: resize, crop, auto-format (automatically selects an appropriate optimized format for the requesting browser), AI background removal, text/image overlays for images; transcoding and adaptive streaming for video
The next-cloudinary SDK gives you drop-in components — <CldImage> wraps next/image, <CldVideoPlayer> handles video — with almost no configuration
Built-in CDN delivery for both, so there's no separate CloudFront-equivalent to wire up

Where Cloudinary struggles:

Free tier (25 credits/month, where 1 credit ≈ 1 GB storage, 1 GB bandwidth, or 1,000 transformations) disappears fast on anything with real traffic — video in particular eats through credits quickly since files are larger
Pricing is credit-based across three different resource types at once, which makes forecasting cost harder than a flat per-GB rate
It's optimized for media-heavy applications; if most of your workload is arbitrary documents and backups, general-purpose object storage is usually a more natural fit

A Minimal Cloudinary Upload + Display in Next.js 16

npm install next-cloudinary cloudinary

// app/api/sign-cloudinary-params/route.ts
import { v2 as cloudinary } from "cloudinary";
import { NextResponse } from "next/server";
import { auth } from "@/lib/auth"; // your auth solution of choice

cloudinary.config({
  cloud_name: process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME,
  api_key: process.env.CLOUDINARY_API_KEY,
  api_secret: process.env.CLOUDINARY_API_SECRET,
});

// The widget generates its own paramsToSign and sends them here — never
// sign that object blindly. Only a small, known set of keys is allowed
// through; anything else gets the whole request rejected.
const ALLOWED_PARAM_KEYS = new Set(["timestamp", "folder", "upload_preset", "source"]);

export async function POST(request: Request) {
  const session = await auth();
  if (!session?.user) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { paramsToSign } = await request.json();
  const keys = Object.keys(paramsToSign ?? {});
  const unexpectedKeys = keys.filter((key) => !ALLOWED_PARAM_KEYS.has(key));

  if (unexpectedKeys.length > 0) {
    return NextResponse.json(
      { error: `Unexpected upload parameters: ${unexpectedKeys.join(", ")}` },
      { status: 400 }
    );
  }

  const signature = cloudinary.utils.api_sign_request(
    paramsToSign,
    process.env.CLOUDINARY_API_SECRET!
  );

  return NextResponse.json({ signature });
}

What's happening here: the widget builds paramsToSign on its own based on how it's configured, and sends that exact object to your endpoint to be signed — so you can't simply substitute your own parameters the way you might for a normal API request, or the signature won't match what the widget actually uploads with. What you can do, and what this endpoint does, is refuse to sign anything that isn't on a small allowlist of expected keys, and require a logged-in session before generating a signature at all. This stops the endpoint from being used to sign arbitrary transformation instructions, moderation overrides, or unexpected metadata that a modified client request might try to sneak in. Once signed, the upload still goes directly from the browser to Cloudinary — your CLOUDINARY_API_SECRET never reaches the client.

💡 Tip: Signed uploads narrow who can request a signature, but the file itself — its folder, allowed formats, and max size — is still best constrained by an upload preset configured in the Cloudinary dashboard (Settings → Upload → Upload presets), since a preset's restrictions are enforced by Cloudinary itself and can't be bypassed by tampering with the request the way a loosely-validated paramsToSign object could be.

// components/cloudinary-uploader.tsx
"use client";

import { useState } from "react";
import { CldUploadWidget, CldImage } from "next-cloudinary";

export function CloudinaryUploader() {
  const [publicId, setPublicId] = useState<string | null>(null);

  return (
    <div>
      <CldUploadWidget
        signatureEndpoint="/api/sign-cloudinary-params"
        options={{ folder: "uploads" }}
        onSuccess={(result) => {
          if (result.info && typeof result.info === "object") {
            setPublicId(result.info.public_id);
          }
        }}
      >
        {({ open }) => (
          <button onClick={() => open()}>Upload an image</button>
        )}
      </CldUploadWidget>

      {publicId && (
        <CldImage
          src={publicId}
          width={600}
          height={400}
          crop="fill"
          alt="Uploaded image"
        />
      )}
    </div>
  );
}

What's happening here: <CldImage> renders the uploaded asset with a crop="fill" transformation applied automatically, on top of next/image's own optimization. Swap this component for <CldVideoPlayer> and the same signed-upload flow works for video uploads, using the same signing endpoint.

⚠️ Common Mistake: Using an unsigned upload preset (no signatureEndpoint, just a public preset name) for anything beyond a quick prototype. Anyone who knows the preset name can initiate uploads subject to the restrictions configured on that preset — fine for a personal demo, risky for anything public-facing.

Media Optimization: Who Actually Handles It?

This is usually the deciding factor in practice, so it's worth calling out directly:

S3 does nothing for you, for images or video. You either accept unoptimized originals, or build your own pipeline (Lambda@Edge, a CloudFront Function, a dedicated transcoding service, or routing S3 through Cloudinary/imgix as a second layer).
Supabase Storage offers a transformation API (resize + quality via query params) that works with a custom Next.js image loader — available only in Paid Plans, and images only; there's no equivalent video pipeline.
Cloudinary is purpose-built for exactly this, for both media types. Automatic format negotiation (AVIF/WebP per browser), on-the-fly cropping, <CldImage>'s tight next/image integration, and adaptive-bitrate video streaming mean you write the least code here.

If your app's core UX depends on fast, well-optimized media at scale — a marketplace, a photo-heavy blog, a portfolio builder, or a product with video uploads (course platforms, social apps, UGC video) — that alone can justify Cloudinary's cost. If media is incidental — a profile picture here, a document there — S3 or Supabase Storage is plenty.

Security Models Compared

	How access is controlled
S3	IAM policies (who can call the API) + bucket policies (what's publicly readable) + presigned URLs for temporary, scoped access
Supabase Storage	Row Level Security policies written in SQL, evaluated per-request against the logged-in user — the same system protecting your database tables
Cloudinary	Signed uploads (server signs the request, ideally after validating it) or unsigned upload presets (public, rate-limited by preset config)

The practical difference: S3 and Cloudinary both support signed requests for scoped upload/access workflows, while Supabase emphasizes identity-aware RLS policies. Supabase Storage centers on who is asking, evaluated through Postgres RLS policies. If your app already has rich, row-level permission logic in Postgres, Supabase Storage lets you reuse that thinking instead of maintaining a parallel IAM policy language — but in all three, a client-constructed path or parameter is never the actual security boundary on its own; the server-side check (RLS, IAM, or a whitelist) is.

Can You Mix Them?

Yes, and plenty of real apps do. A common pattern:

S3 (or Cloudflare R2, an S3-compatible alternative) for cheap, high-volume storage of originals — documents, raw uploads, backups
Cloudinary in front of just the media subset (images and video), either by uploading directly to Cloudinary or using its remote fetch feature to transform images that already live in S3
Supabase Storage for anything tightly coupled to your Supabase-authenticated user data, where RLS access rules matter more than transformation power

There's no rule that says "pick exactly one." Reach for the tool that fits that specific type of file, not a single storage layer for your entire app by default.

Decision Matrix

Your situation	Pick
Already deep in AWS infrastructure	S3
Need the cheapest storage at real scale, and can account for request/transfer costs	S3 / R2 depending on egress profile
Already using Supabase for auth + database	Supabase Storage
Want row-level access rules without a separate IAM setup	Supabase Storage
Images/video are core to your product's UX	Cloudinary
Want automatic format optimization with near-zero setup	Cloudinary
Storing mostly non-image files (PDFs, CSVs, backups)	S3
Small MVP, want the fastest path to "it works"	Supabase Storage if the app already uses Supabase; Cloudinary if images or video are central.

Frequently Asked Questions

Is Supabase Storage actually built on S3?

Supabase Storage is S3-compatible and exposes an S3 protocol endpoint, so tools that speak the S3 API can interact with it. The important distinction is that Supabase adds its own API, authentication integration, and Postgres RLS model.

Do I need Cloudinary if I'm already using next/image?

Not necessarily. next/image already handles resizing, format conversion, and lazy loading for images you serve from S3 or Supabase Storage — it just needs the source domain allowlisted in remotePatterns. Reach for Cloudinary specifically when you need transformations next/image doesn't do itself, like AI background removal, video transcoding, or on-the-fly cropping driven by user input.

Which one is cheapest for a small side project?

For a small MVP, Supabase Storage is attractive if you're already using Supabase, while Cloudinary is attractive when image or video transformations are central. S3 can also be inexpensive, but remember it's billed across storage, requests, and data transfer separately — factor in all three before assuming it's the cheapest option for your specific traffic pattern.

Is a presigned S3 upload URL alone enough security?

No. A presigned URL controls whether an upload to a specific key is allowed within its expiry window — it doesn't validate file type, size, or content on its own beyond what you sign into the request. Pair it with server-side checks (auth, MIME allowlist, size limits) before issuing the URL, as shown in this guide's example, and treat anything beyond that (checksums, virus scanning, rate limiting) as genuinely needed for production, not optional polish.

Can I switch between these later without a full rewrite?

Keeping storage access behind a small abstraction makes migration easier. The files themselves may be easy to migrate; the harder part is usually recreating URLs, access-control rules, transformations, and metadata.

Does Cloudinary replace the need for a CDN?

Yes — Cloudinary delivers every asset through its own CDN by default, so you don't need to add CloudFront or another CDN in front of it the way you would with raw S3.

What about Cloudflare R2 as another alternative?

R2's S3-compatible API makes many application patterns—such as presigned URLs and S3 SDK usage—very similar to S3, although its pricing and access-control model differ.

Wrapping Up

None of these three is a universally "better" choice — they're solving different halves of the same problem. S3 gives you the cheapest, most flexible raw storage and expects you to build the rest, including the parts of its own billing model (requests, transfer, retrieval) that are easy to overlook. Supabase Storage trades some of that flexibility for tight integration with the auth and database system you're probably already using — just remember that a client-supplied path is never the actual security boundary; the RLS policy is. Cloudinary trades storage cost for a transformation pipeline — for images and video — that would otherwise take real engineering time to build yourself.

Start by asking what you're actually storing and who needs to see it — that answer usually points to one of these three faster than a feature-by-feature comparison ever will.

Continue Learning

Free Developer Tools

Supabase RLS Policy Generator — generate strict, pattern-specific Row Level Security policies for your storage buckets, including the owner-only pattern shown in this guide.

Auth.js vs Better Auth in 2026: Which Should You Use?

Syed Muhammad Ali — Tue, 25 Aug 2026 04:07:06 +0000

You're starting a new Next.js project and you need auth. A year ago the answer was simple: "just use NextAuth." That's not simple anymore. NextAuth is now called Auth.js, it's sitting in maintenance mode, and the team that used to build it has folded into a different project entirely — Better Auth, which Vercel just bought.

If you Google "Auth.js vs Better Auth" today, half the results are outdated and the other half assume you already know the backstory. You don't need the backstory to make a good decision — you just need the current facts, side by side, with real code. That's what this guide gives you.

By the end, you'll know exactly what each library does well, what each one is missing, and which one fits your project — whether that's a solo side project, a client SaaS app, or something you're migrating from an old NextAuth v4 codebase.

Why This Comparison Is Confusing Right Now

Three things changed in a short window, and most tutorials online haven't caught up:

NextAuth renamed itself Auth.js when it expanded beyond Next.js to support other frameworks. The npm package is still called next-auth — only the project's public name changed.
Auth.js is now maintained by Better Auth Inc., not its original team. Since early 2026, Auth.js has been in maintenance mode: security patches only, no new features.
Vercel acquired Better Auth on July 7, 2026. Better Auth stays free, MIT-licensed, and open source — Vercel says it isn't closing that off — but it's now the auth library with Vercel's own resources and roadmap behind it, not a scrappy independent project.

Put simply: if you pick Auth.js today, you're picking a stable, feature-frozen library. If you pick Better Auth, you're picking the actively developed one that absorbed Auth.js's own team.

That doesn't automatically make Better Auth the right answer for every project — "actively developed" and "right for you" aren't the same thing. Let's get into specifics.

Quick Answer

Choose Auth.js (NextAuth) if you're maintaining an existing NextAuth v4/v5 codebase, you only need OAuth + JWT sessions with zero extra features, or you want the library with the longest production track record.
Choose Better Auth if you're starting a new project today and want built-in passkeys, 2FA, organizations, or RBAC without hand-rolling them, or you want a library that's still receiving new features.

For a brand-new Next.js project in 2026 with no existing NextAuth investment, Better Auth is the stronger default. Now here's why.

                         AUTH.JS
                            │
                  ┌─────────┴─────────┐
                  │                   │
             JWT sessions        DB sessions
                  │                   │
             no DB required       DB required


                      BETTER AUTH
                           │
              ┌────────────┴────────────┐
              │                         │
        Stateless mode            Database mode
              │                         │
          no DB required          DB-backed sessions
                                        │
                           ┌────────────┼────────────┐
                           │            │            │
                       Passkeys       2FA      Organizations
                                      │            │
                                  DB-backed    DB-backed
                                  features     features

What Each Library Actually Is

Auth.js (formerly NextAuth)

Auth.js is a session and OAuth layer built specifically around Next.js's App Router conventions. You configure a single auth.ts file, wire it into a catch-all route handler, and call auth() anywhere on the server to read the current session.

npm install next-auth@beta

⚠️ Common Mistake: Running npm install next-auth without the @beta tag installs the old v4 API (authOptions, getServerSession(), a completely different setup). As of mid-2026, next-auth@latest still resolves to v4 — v5 is only reachable through the beta tag, even though it's what almost every current tutorial (including this one) assumes.

// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [GitHub],
});

// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";
export const { GET, POST } = handlers;

That's a complete, working GitHub OAuth setup — no database required if you're fine with JWT sessions. auth() is now the single entry point for reading the session anywhere on the server, replacing the old v4 pattern of getServerSession(authOptions).

Better Auth

Better Auth is framework-agnostic (Next.js, Nuxt, SvelteKit, TanStack Start, plain Node) and TypeScript-first. Instead of one library that does OAuth and sessions, it ships a small core plus a plugin system — passkeys, 2FA, organizations, and RBAC are opt-in plugins, not separate libraries you bolt on yourself.

npm install better-auth

// lib/auth.ts
import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { db } from "@/lib/db";

export const auth = betterAuth({
  database: drizzleAdapter(db, { provider: "pg" }),
  emailAndPassword: {
    enabled: true,
  },
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    },
  },
});

// app/api/auth/[...all]/route.ts
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";

export const { POST, GET } = toNextJsHandler(auth);

What's happening here: toNextJsHandler() is Better Auth's official helper for wiring its core into a Next.js App Router catch-all route — it maps every request under /api/auth/* to the right internal handler, the same way Auth.js's handlers export does.

💡 Tip: The folder is app/api/auth/[...all]/route.ts, not [...nextauth]. Better Auth's catch-all segment name is arbitrary — it just needs to match whatever basePath you configure on the client (the default is /api/auth).

Better Auth Can Also Run Without a Database Now

For a long time, "no database, no Better Auth" was the biggest practical reason to reach for Auth.js instead. That gap closed with Better Auth 1.4 (November 2025): you can now omit the database option entirely and run fully stateless, signed-cookie sessions — the same JWT-style model Auth.js has always defaulted to.

// lib/auth.ts — stateless, no database at all
import { betterAuth } from "better-auth";

export const auth = betterAuth({
  // No `database` option — session data lives in a signed/encrypted cookie
  socialProviders: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
  },
});

What's happening here: with no database configured, Better Auth verifies session cookies by signature and expiry instead of looking them up in a table — functionally the same trade-off as Auth.js's JWT sessions (fast, no DB round trip, but no server-side "delete this one session" revocation).

⚠️ Common Mistake: Assuming stateless mode unlocks the full plugin ecosystem too. Better Auth's own docs are explicit that most plugins still require a database — passkey(), organization(), and two-factor auth all persist real records (credentials, memberships, invitations) that a signed cookie can't hold. Stateless mode covers basic email/password and OAuth sign-in; reach for a database the moment you add a plugin.

So the database gap between the two libraries has narrowed for basic auth, but it's still real the moment you want any of Better Auth's headline plugin features.

Setup Time

Auth.js, with JWT sessions and one OAuth provider, is genuinely the fastest path to a working sign-in flow — install, create auth.ts, add the route handler, done. No database, no schema migration.

Better Auth, with a database adapter (Drizzle, Prisma, Kysely, or a handful of others), needs one extra step — generating and applying the schema — before it will run:

npx auth@latest generate
npx auth@latest migrate

💡 Tip: These commands used to live under a separate @better-auth/cli package. As of 2026 the CLI is published as the auth package on npm and invoked with npx auth@latest <command> — if you see npx @better-auth/cli generate in an older tutorial, it's the same tool under its previous name.

That's a few extra minutes of setup compared to Auth.js's JWT mode — but it's also the reason a database-backed Better Auth setup gets you a real user table, instant session revocation, and its plugin ecosystem for free once it's running. If you don't want the database at all, Better Auth's stateless mode closes most of that setup-time gap for basic email/password and OAuth sign-in — the schema migration step above is only needed once you configure a database or add a plugin that requires one.

💡 Tip: Even without your own feature needs pointing you one way or the other, this is still a reasonable rule of thumb: default to Auth.js (or Better Auth's stateless mode) for a genuinely tiny side project, and to a database-backed Better Auth setup for anything that will eventually need passkeys, 2FA, organizations, or persistent user records.

Reading the Session

Auth.js — Server Component

// app/dashboard/page.tsx
import { auth } from "@/auth";

export default async function DashboardPage() {
  const session = await auth();

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

Better Auth — Server Component

// app/dashboard/page.tsx
import { auth } from "@/lib/auth";
import { headers } from "next/headers";

export default async function DashboardPage() {
  const session = await auth.api.getSession({
    headers: await headers(),
  });

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

What's different here: Auth.js's auth() reads cookies internally with no extra arguments. Better Auth's server-side session check is a plain API method (auth.api.getSession) that you explicitly pass request headers into — a small but real difference in ergonomics, since you have to remember the headers() call every time.

Better Auth — Client Component

// components/user-menu.tsx
"use client";

import { authClient } from "@/lib/auth-client";

export function UserMenu() {
  const { data: session, isPending } = authClient.useSession();

  if (isPending) return null;
  if (!session) return <a href="/sign-in">Sign in</a>;

  return <span>Welcome, {session.user.name}</span>;
}

// lib/auth-client.ts
import { createAuthClient } from "better-auth/react";

export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_APP_URL,
});

What's happening here: createAuthClient() from better-auth/react gives you a typed useSession() hook that stays in sync with the server — if the session expires or the user signs out in another tab, it updates automatically. Auth.js has the equivalent useSession() hook from next-auth/react, wrapped in a <SessionProvider> at the root of your app.

Feature Comparison

Feature	Auth.js (v5)	Better Auth
Status	Maintenance mode — security patches only	Actively developed, now backed by Vercel
Requires a database	No (JWT sessions work standalone)	No for basic auth since v1.4 (stateless mode) — still required for most plugins (passkeys, 2FA, organizations)
Session model	JWT by default, database sessions optional	Database sessions by default, stateless signed-cookie sessions optional since v1.4
OAuth providers	Large built-in provider ecosystem	Built in, growing list
Passkeys (WebAuthn)	Not built in — experimental `Passkey` provider exists but needs an adapter & is marked not production-ready	Built-in `passkey()` plugin, ~10 lines of config
Two-factor auth	Build it yourself	Built-in plugin
Organizations / multi-tenancy	Build it yourself	Built-in plugin
Role-based access control	Build it yourself	Built-in plugin
Framework support	Next.js-first (also SvelteKit, Express via `@auth/core`)	Framework-agnostic — Next.js, Nuxt, SvelteKit, TanStack Start, Expo, plain Node
Instant session revocation	Only with database sessions	Yes, by default
Edge runtime friendly	Yes, with JWT sessions	Depends on adapter/runtime support

Passkeys: The Feature Gap That Matters Most

If passkey sign-in is a requirement, this is where the two libraries genuinely diverge, not just in convenience.

Auth.js ships an experimental Passkey provider, but the docs are explicit that it's not recommended for production, and it requires switching from stateless JWT sessions to a full database adapter just to use it — a real architectural change, not a one-line addition.

Better Auth treats passkeys as a first-class plugin:

npm install @better-auth/passkey

// lib/auth.ts
import { betterAuth } from "better-auth";
import { passkey } from "@better-auth/passkey";

export const auth = betterAuth({
  // ...your database and provider config
  plugins: [passkey()],
});

// lib/auth-client.ts
import { createAuthClient } from "better-auth/react";
import { passkeyClient } from "@better-auth/passkey/client";

export const authClient = createAuthClient({
  plugins: [passkeyClient()],
});

What's happening here: the passkey() plugin (powered by SimpleWebAuthn internally) adds the database fields, registration flow, and authentication flow for you. After running the CLI migration, users can register and sign in with Face ID, Windows Hello, or a hardware key with no custom WebAuthn code on your end.

⚠️ Common Mistake: Forgetting to run npx auth@latest migrate (or generate + your ORM's own migration step) after adding a new plugin like passkey() or organization(). Each plugin adds its own tables/columns, and — since passkeys need somewhere to persist credentials — this is also exactly the case where Better Auth's stateless, no-database mode stops being an option. The plugin will fail at runtime, not build time, if the schema hasn't caught up.

Organizations and Multi-Tenant Apps

If you're building B2B SaaS — teams, workspaces, invitations, per-organization roles — this is the other place the gap is large.

Auth.js has no organizations concept at all. You'd model teams yourself with your own database tables and write your own invitation, membership, and permission logic on top of Auth.js's session.

Better Auth has this as a plugin:

// lib/auth.ts
import { betterAuth } from "better-auth";
import { organization } from "better-auth/plugins";

export const auth = betterAuth({
  // ...your database and provider config
  plugins: [organization()],
});

This one plugin gives you organization creation, invitations, member roles, and the database schema for all of it.

Security: Don't Rely on Middleware Alone, With Either Library

This applies regardless of which one you pick. Next.js had a documented middleware bypass (CVE-2025-29927) where a spoofed header could skip middleware checks entirely — including auth checks. It's patched now, but it's a good reminder that proxy.ts (the renamed middleware.ts in Next.js 16) should never be your only line of defense.

// Inside a Server Action, regardless of which library you use
const session = await auth(); // Auth.js
// or
const session = await auth.api.getSession({ headers: await headers() }); // Better Auth

if (!session) {
  return { error: "Unauthorized" };
}

Always re-check the session inside Server Actions and Route Handlers that touch real data. Treat proxy.ts redirects as a UX nicety — a way to bounce an obviously-signed-out user before a page even renders — not your actual security boundary.

💡 Tip: If you're not familiar with how sessions and JWTs differ under the hood — including why database sessions support instant revocation and JWTs don't — see Session vs JWT: Which Should You Use in Next.js 16? for the full breakdown.

Pricing

Both libraries are free and open source under MIT. Neither charges per user, per seat, or per monthly active user — that's the core pitch of self-hosted auth versus a managed service like Clerk.

The real cost difference is development time, not license fees:

	Auth.js	Better Auth
License cost	$0	$0
Hosting cost	Only if using database sessions	Only if you add a database (needed for persistent users or most plugins)
Dev time for passkeys / 2FA / orgs	You build it	Plugin, minutes of config — requires a database
Dev time for basic OAuth + sessions	Minutes	Minutes, stateless mode needs no DB setup at all

If you need advanced features, Auth.js's "free" license comes with a real time cost — you're the one building 2FA or organizations from scratch. Better Auth trades a slightly longer initial setup for a lot less custom code later.

Migrating From Auth.js to Better Auth

If you already have a working Auth.js app and are considering a move, know this upfront: it's a parallel implementation, not a drop-in swap. The session models are different enough (JWT vs. database sessions by default, different table shapes) that a big-bang cutover is riskier than it needs to be.

A safer path:

Add Better Auth alongside your existing Auth.js setup, on new routes only.
Migrate your user table to Better Auth's schema using its CLI (npx auth@latest generate, then a manual data migration script for existing users — Better Auth doesn't do this part for you).
Move features one at a time — start with sign-in/sign-up, then migrate protected routes, then remove Auth.js once nothing depends on it.
If you need zero-downtime migration, design an explicit transition strategy so existing Auth.js sessions can continue working while Better Auth is introduced.

💡 Tip: Migration can require manual schema and identity mapping, so test the migration path before production cutover

If you have no existing NextAuth investment, skip this section entirely — just start with whichever library fits your feature needs from Step 1 above.

Decision Table

Your situation	Pick
Maintaining an existing NextAuth v4/v5 app	Auth.js
New project, only need OAuth + basic sessions, no database yet	Auth.js (JWT mode) or Better Auth (stateless mode) — either works
New project, want passkeys or 2FA without building them yourself	Better Auth (needs a database for these plugins)
B2B SaaS needing organizations, teams, or RBAC	Better Auth
Need Edge-runtime session checks with zero database calls	Auth.js (JWT mode)
Want instant, guaranteed session revocation by default	Better Auth
Building outside Next.js too (Nuxt, SvelteKit, Expo)	Better Auth
Want the library actively gaining features month over month	Better Auth

Frequently Asked Questions

Is Auth.js dead?

No — it's in maintenance mode, not abandoned. It still receives security patches, and existing apps using it don't need to migrate urgently. What's stopped is new feature development; that work moved to Better Auth after the Better Auth team took over Auth.js's maintenance.

Is NextAuth the same thing as Auth.js?

Yes. NextAuth renamed itself to Auth.js when it expanded beyond Next.js to other frameworks. The npm package is still installed as next-auth for backwards compatibility — only the public project name changed.

Does Better Auth work with the Next.js App Router?

Yes, and it's first-class supported. Better Auth ships a toNextJsHandler() helper specifically for wiring its core into an App Router catch-all route, and its React client works in both Server and Client Components with the patterns shown above.

Do I need a database for Better Auth?

Not necessarily anymore. As of Better Auth 1.4 (November 2025), you can omit the database option entirely and run stateless, signed-cookie sessions — the same JWT-style trade-off as Auth.js. You'll still need a database adapter (Drizzle, Prisma, Kysely, and others are supported) the moment you want persistent user records or most plugins, since the docs are explicit that plugins like passkey(), organization(), and two-factor auth require one.

Has the Better Auth CLI command changed?

Yes. It used to be published under @better-auth/cli; it's now the auth package on npm, invoked as npx auth@latest generate and npx auth@latest migrate (plus newer commands like info and create-admin). If you see @better-auth/cli in an older tutorial, it's the same tool under its previous package name — the underlying generate/migrate behavior hasn't changed.

Will Vercel's acquisition of Better Auth change the pricing or license?

As of the acquisition, Vercel confirmed Better Auth stays free and MIT-licensed, keeps its name, and the original team continues leading development with the same open contribution model. There's no indication of a license change.

Can I use Better Auth outside of Next.js?

Yes — that's one of its core differences from Auth.js. Better Auth is framework-agnostic and has documented support for Nuxt, SvelteKit, TanStack Start, Express, Hono, and even Expo for React Native, all sharing the same core auth logic.

Wrapping Up

Auth.js and Better Auth solve the same core problem — proving who a user is and keeping that state in sync across your app — but they're at very different points in their lifecycle right now. Auth.js is stable, well-documented, and frozen in scope. Better Auth is younger, can now run database-free for basic auth just like Auth.js, and is where the ecosystem's energy (and now Vercel's resources) are actually going — the database is only a hard requirement once you reach for its plugin ecosystem.

For a brand-new Next.js project in 2026 with no legacy NextAuth code to maintain, Better Auth is the safer long-term bet, especially if passkeys, 2FA, or organizations are anywhere on your roadmap. If you're maintaining something that already runs on Auth.js and it's not causing problems, there's no urgency to rip it out — keep shipping, and revisit the decision only when you hit a feature Auth.js genuinely can't give you.

From here, a natural next step is pairing whichever library you pick with Role-Based Access Control on top of the session, or reading Session vs JWT in Next.js 16 to decide which session model actually fits your app before you commit to one.

Continue Learning

Free Developer Tools

Supabase RLS Policy Generator — pair this guide's application-level RBAC with database-level Row Level Security. Generates owner-only, team, and admin-override policies with the auth.uid() performance wrapper built in.
Zod Schema Generator — generate a validated schema for your role/permission payloads straight from a JSON sample or TypeScript interface, including a ready-to-use Server Action.
Vercel Cron Expression Generator - generate Vercel-compatible cron expressions with a visual schedule builder, live validation, & a preview of the next 5 execution times in UTC.

Stripe Refunds & Disputes in Next.js 16 (2026)

Syed Muhammad Ali — Sun, 23 Aug 2026 04:55:41 +0000

Sooner or later, every Stripe integration hits the same wall: a customer wants their money back, or worse, their bank files a chargeback before they even email you. Most Stripe tutorials stop at "payment succeeded" and leave you to figure out refunds and disputes on your own — usually while a real customer is waiting.

This guide fills that gap. You'll learn how refunds and disputes actually differ under the hood, how to build a working refund flow with Server Actions in Next.js 16, how to listen for the webhook events that keep your database in sync, and how to submit dispute evidence through the API instead of digging through the Stripe Dashboard every time. Every code snippet here is checked against Stripe's current API reference and Node SDK, so you can copy it straight into a real project.

Refunds vs. Disputes: Not the Same Problem

These two get lumped together constantly, but they're triggered by completely different people and solved with completely different code.

A refund is something you initiate. A customer emails you, you agree, you send their money back. You're in control of the timing and the amount.
A dispute (also called a chargeback) is something the customer's bank initiates. They contact their card issuer directly, skipping you entirely. The disputed amount plus a dispute fee gets pulled from your Stripe balance immediately, and you only find out because Stripe sends you a webhook.

That difference — "I chose to do this" versus "this happened to me" — is why they need separate code paths, separate webhook listeners, and separate UI. Refunds are proactive; disputes are reactive, with a clock already running before you've read the notification.

💡 Tip: A well-handled refund can sometimes prevent a dispute entirely — if you refund a suspicious or unhappy customer fast enough, their bank never gets involved. That's the main reason to treat refunds as a first-class feature instead of a Dashboard afterthought.

Prerequisites

This guide uses:

Next.js 16 with the App Router
TypeScript in strict mode
Stripe Node SDK (stripe package, latest version)
A Stripe account in test mode
Basic familiarity with Stripe Payment Intents (see our Stripe Payment Element guide if you haven't built a checkout flow yet)

Step 1: Set Up the Stripe Server Client

If you've already got a Stripe integration, you likely have this file already — reuse it instead of creating a second Stripe instance.

// lib/stripe/server.ts
import Stripe from "stripe";

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2026-07-29.dahlia",
});

⚠️ Common Mistake: Never import this file into a Client Component. STRIPE_SECRET_KEY must stay server-only — it can create refunds and pull money out of your account, so treat it with the same care as a database password.

Part 1: Refunds

Step 2: Understand What You Can Actually Refund

Before writing code, know the rules Stripe enforces on every refund request:

You refund against a Payment Intent or a Charge — not an order ID from your own database.
You can refund the full amount or a partial amount, and you can issue multiple partial refunds until the charge is fully refunded.
Once a charge is fully refunded, trying to refund it again throws an error.
You can't refund more than what's left unrefunded on the charge.
Refunds go back to the original payment method — you can't redirect a refund to a different card or bank account.

⚠️ Common Mistake: Trying to refund based on your own internal order status without checking the actual remaining refundable amount on the Stripe side first. If a customer support agent issued a partial refund yesterday and someone tries to refund the full original amount today, Stripe will reject it — always let the error message guide the UI, don't assume the full amount is always available.

Step 3: Create a Refund Server Action

This is the core building block — a Server Action that creates a refund against a Payment Intent, with an idempotency key so a network retry never creates two refunds for the same request.

// actions/create-refund.ts
"use server";

import { randomUUID } from "crypto";
import { stripe } from "@/lib/stripe/server";
import type Stripe from "stripe";

export type RefundState = {
  success?: boolean;
  error?: string;
  refundId?: string;
  status?: string;
};

export async function createRefund(
  _prev: RefundState,
  formData: FormData
): Promise<RefundState> {
  const paymentIntentId = formData.get("paymentIntentId") as string;
  const amountInput = formData.get("amount") as string; // dollars, from the form
  const reason = formData.get("reason") as string;

  if (!paymentIntentId) {
    return { error: "Payment Intent ID is required" };
  }

  try {
    const params: Stripe.RefundCreateParams = {
      payment_intent: paymentIntentId,
    };

    // Only set `amount` for a partial refund — omitting it refunds the full remaining balance
    if (amountInput) {
      params.amount = Math.round(Number(amountInput) * 100); // Stripe expects cents
    }

    if (reason === "duplicate" || reason === "fraudulent" || reason === "requested_by_customer") {
      params.reason = reason;
    }

    // Generated once per form submission — reused automatically if this exact
    // request is retried, so a flaky network never creates a duplicate refund
    const idempotencyKey = randomUUID();

    const refund = await stripe.refunds.create(params, { idempotencyKey });

    return { success: true, refundId: refund.id, status: refund.status ?? undefined };
  } catch (err) {
    return {
      error: err instanceof Error ? err.message : "Something went wrong while processing the refund.",
    };
  }
}

What's happening here:

payment_intent is the only required field — Stripe finds the underlying charge for you, so you never need to look up a separate charge ID.
amount is optional. Leave it out entirely for a full refund; set it for a partial one. Stripe amounts are always in the smallest currency unit (cents for USD), so a $12.50 refund is 1250, not 12.5.
reason is optional and only accepts three values: duplicate, fraudulent, or requested_by_customer. It's mostly for your own reporting and Stripe's Dashboard filtering — it doesn't change how the refund is processed.
The idempotencyKey argument is the second parameter to stripe.refunds.create(), not part of the request body. Generate it once per logical refund attempt (once per form submit), not once per retry — that's what makes it protect against duplicates.

⚠️ Common Mistake: Generating a new randomUUID() inside a retry loop instead of once per user action. If the key changes on every retry, Stripe treats each attempt as a brand-new refund request — which defeats the entire point of passing one.

Step 4: Build a Simple Refund Form

Here's a minimal admin-facing form using useActionState, the same pattern used throughout this site's Stripe guides.

// components/refund-form.tsx
"use client";

import { useActionState } from "react";
import { createRefund, type RefundState } from "@/actions/create-refund";

const initialState: RefundState = {};

export function RefundForm({ paymentIntentId }: { paymentIntentId: string }) {
  const [state, formAction, isPending] = useActionState(createRefund, initialState);

  return (
    <form action={formAction} className="flex flex-col gap-3 max-w-sm">
      <input type="hidden" name="paymentIntentId" value={paymentIntentId} />

      <label className="flex flex-col gap-1 text-sm">
        Amount to refund (leave blank for full refund)
        <input
          name="amount"
          type="number"
          step="0.01"
          min="0"
          placeholder="e.g. 12.50"
          className="rounded-lg border px-3 py-2"
        />
      </label>

      <label className="flex flex-col gap-1 text-sm">
        Reason
        <select name="reason" className="rounded-lg border px-3 py-2">
          <option value="requested_by_customer">Requested by customer</option>
          <option value="duplicate">Duplicate charge</option>
          <option value="fraudulent">Fraudulent</option>
        </select>
      </label>

      <button
        type="submit"
        disabled={isPending}
        className="rounded-lg bg-primary px-4 py-2 text-white disabled:opacity-50"
      >
        {isPending ? "Processing…" : "Issue Refund"}
      </button>

      {state.success && (
        <p className="text-sm text-green-600">
          Refund created ({state.refundId}) — status: {state.status}
        </p>
      )}
      {state.error && <p className="text-sm text-destructive">{state.error}</p>}
    </form>
  );
}

What's happening here: the paymentIntentId comes in as a prop (from wherever your order/payment lookup lives) and rides along as a hidden field, so the Server Action always knows exactly which payment it's refunding — the amount field is the only thing an admin actually types.

💡 Tip: Card refunds usually show a status of succeeded almost immediately, but some refund methods — bank transfers, certain wallets — settle asynchronously and start at pending. Don't assume succeeded the moment stripe.refunds.create() resolves; treat the webhook in the next step as the real source of truth.

Step 5: Understand `pending_reason` and `failure_reason`

A refund's status can land on pending or failed, and each has its own dedicated field explaining why — don't confuse the two, they're separate fields that only carry a value for their matching status.

pending_reason — only set when status: "pending":

`pending_reason`	Meaning
`processing`	The refund is being processed normally — just wait
`insufficient_funds`	Your Stripe balance can't currently cover the refund
`charge_pending`	The original payment hasn't fully settled yet, so it can't be refunded yet

failure_reason — only set when status: "failed":

`failure_reason`	Meaning
`charge_for_pending_refund_disputed`	The customer disputed the charge while this refund was still pending — Stripe automatically fails the refund here to stop you from reimbursing the customer twice (once via the dispute, once via the refund)
`insufficient_funds`	The refund stayed pending too long waiting on balance and ultimately failed
`lost_or_stolen_card` / `expired_or_canceled_card`	The destination card can no longer accept the refund
`declined`	Declined by Stripe's financial partners
`merchant_request`	The refund was canceled at your request
`unknown`	Failed for an unspecified reason

const refund = await stripe.refunds.create({ payment_intent: paymentIntentId });

if (refund.status === "pending" && refund.pending_reason === "insufficient_funds") {
  // Surface this to your finance/ops team — your Stripe balance needs topping up
}

if (refund.status === "failed" && refund.failure_reason === "charge_for_pending_refund_disputed") {
  // A dispute was filed while this refund was in flight — go handle the
  // dispute instead of retrying the refund, per Stripe's own guidance
}

💡 Tip: insufficient_funds is a valid value for both fields, but it means something different depending on which one you're reading — on pending_reason it means "still waiting," on failure_reason it means "gave up waiting and failed." Always check status first to know which field is actually meaningful.

Part 2: Webhooks for Refunds

Step 6: Listen for `refund.created`, `refund.updated`, and `refund.failed`

Your Server Action creating the refund only tells you the request was accepted — not that money actually landed back on the customer's card. Webhooks are what confirm the real outcome, the same way payment_intent.succeeded is the real source of truth for a payment, not the client-side redirect.

// app/api/webhook/route.ts
import { NextResponse } from "next/server";
import { headers } from "next/headers";
import Stripe from "stripe";
import { stripe } from "@/lib/stripe/server";

const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET!;

export async function POST(req: Request) {
  const payload = await req.text(); // raw body — required for signature verification
  const signature = (await headers()).get("stripe-signature");

  if (!signature) {
    return NextResponse.json({ error: "Missing signature" }, { status: 400 });
  }

  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(payload, signature, endpointSecret);
  } catch (err) {
    const message = err instanceof Error ? err.message : "Unknown error";
    return NextResponse.json({ error: `Webhook Error: ${message}` }, { status: 400 });
  }

  switch (event.type) {
    case "refund.created": {
      const refund = event.data.object as Stripe.Refund;
      console.log("Refund initiated:", refund.id, refund.status);
      // TODO: mark the order as "refund pending" in your database
      break;
    }

    case "refund.updated": {
      const refund = event.data.object as Stripe.Refund;
      if (refund.status === "succeeded") {
        console.log("Refund completed:", refund.id);
        // TODO: mark the order as refunded, notify the customer by email
      }
      break;
    }

    case "refund.failed": {
      const refund = event.data.object as Stripe.Refund;
      console.warn("Refund failed:", refund.id, refund.failure_reason);

      if (refund.failure_reason === "charge_for_pending_refund_disputed") {
        // A dispute landed on this charge while the refund was still in
        // flight. Don't retry the refund — go handle the dispute instead.
      } else {
        // TODO: alert your team — this needs manual follow-up, the customer wasn't paid back
      }
      break;
    }

    default:
      break;
  }

  return NextResponse.json({ received: true }, { status: 200 });
}

What's happening here:

refund.created, refund.updated, and refund.failed now fire for every refund type — card, bank transfer, wallet — not just refunds without an associated charge. This changed in a Stripe API update; on older pinned API versions, you may only see the equivalent information inside a charge.refunded event instead. If you're not sure which version you're on, check Stripe-Version in your Dashboard settings.
req.text() reads the raw body — exactly like every other Stripe webhook handler on this site. Calling req.json() first breaks signature verification.
Returning 200 for events you don't act on (the default case) matters — Stripe retries anything that doesn't get a 2xx response, and you don't want it retrying forever over an event type you're intentionally ignoring.

⚠️ Common Mistake: Marking an order "refunded" the moment your Server Action's stripe.refunds.create() call resolves, instead of waiting for the refund.updated webhook with status: "succeeded". A refund can still fail after being accepted — insufficient balance, an invalid destination — and your database would say "refunded" for money the customer never actually received.

Step 7: Prevent Duplicate Processing

Just like payment webhooks, refund webhooks can be delivered more than once. Reuse the same idempotent-event pattern: store processed event IDs with a unique constraint, and skip anything you've already handled.

-- Reuse the same table if you already track processed payment webhook events
create table if not exists processed_webhook_events (
  id uuid primary key default gen_random_uuid(),
  stripe_event_id text unique not null,
  processed_at timestamptz default now()
);

// Inside the switch statement, before doing real work
const alreadyProcessed = await hasProcessedEvent(event.id);
if (alreadyProcessed) {
  return NextResponse.json({ received: true, duplicate: true });
}

// ... handle the event ...

await markEventProcessed(event.id);

💡 If you haven't set this up yet, our Stripe webhook idempotency guide covers the full pattern — signature verification, idempotency keys, and duplicate-event tracking — in more depth than this post has room for.

Part 3: Disputes

Step 8: What Happens When a Dispute Is Filed

A dispute is a formal claim a cardholder files with their bank, not with you. The moment it's created:

Stripe immediately debits the disputed amount, plus a separate dispute fee, from your account balance.
Stripe fires a charge.dispute.created webhook — this is usually how you find out at all.
You get a limited window to submit evidence proving the charge was legitimate. The exact deadline is in dispute.evidence_details.due_by and varies by card network — don't hardcode a number of days.
If you don't respond in time, the dispute is automatically decided against you and the funds stay with the customer's bank.

⚠️ Don't try to refund your way out of a dispute. Once a dispute exists, the bank has already reimbursed the customer directly — issuing your own refund on top of that doesn't reverse the chargeback, it just risks paying the customer twice. Stripe's guidance is explicit that a formally disputed payment should be addressed through the dispute process (evidence or acceptance), not a manual refund. There's also one automated backstop worth knowing: if you'd already started a refund and a dispute is filed on that same charge while the refund is still pending, Stripe fails the refund on its own with failure_reason: "charge_for_pending_refund_disputed" — see Step 5. That backstop only covers that specific race condition, though, not every case of refunding an already-disputed charge, so don't rely on the API to stop you — check for an open dispute yourself before refunding.

Step 9: Listen for Dispute Webhooks

Disputes go through their own lifecycle of events, separate from refunds:

// app/api/webhook/route.ts (continued — same switch statement as Step 6)
case "charge.dispute.created": {
  const dispute = event.data.object as Stripe.Dispute;

  console.log("New dispute:", dispute.id, dispute.reason, dispute.amount);
  console.log("Evidence due by:", new Date(dispute.evidence_details.due_by * 1000));

  // TODO: store the dispute, alert your team immediately — the clock is already running
  break;
}

case "charge.dispute.updated": {
  const dispute = event.data.object as Stripe.Dispute;
  console.log("Dispute updated:", dispute.id, dispute.status);
  // TODO: sync the latest status/evidence state to your database
  break;
}

case "charge.dispute.closed": {
  const dispute = event.data.object as Stripe.Dispute;
  console.log("Dispute closed:", dispute.id, dispute.status); // "won" or "lost"
  // TODO: if "won", funds return to your balance automatically — just update your records
  break;
}

case "charge.dispute.funds_withdrawn": {
  const dispute = event.data.object as Stripe.Dispute;
  // Fires when the disputed amount + fee is actually deducted from your balance
  break;
}

case "charge.dispute.funds_reinstated": {
  const dispute = event.data.object as Stripe.Dispute;
  // Fires when you win and the funds are returned
  break;
}

What's happening here: dispute.reason tells you why the cardholder is disputing (fraudulent, product_not_received, duplicate, and several others), which is useful for automatically routing the dispute to the right evidence template. evidence_details.due_by is a Unix timestamp — multiply by 1000 before passing it to new Date() in JavaScript.

💡 Tip: Some card networks send pre-dispute alerts before a formal dispute is even filed — a chance to refund proactively and avoid the dispute (and its fee) entirely. These arrive as separate events from your fraud/alert tooling, not charge.dispute.created, so don't assume silence means you're safe until the formal dispute webhook actually fires.

Step 10: Submit Dispute Evidence Through the API

You can respond to a dispute entirely from your dashboard, but doing it through the API means you can pull evidence — order details, tracking numbers, support conversation logs — directly from your own database instead of copy-pasting into a web form.

// actions/submit-dispute-evidence.ts
"use server";

import { stripe } from "@/lib/stripe/server";
import type Stripe from "stripe";

interface EvidenceInput {
  disputeId: string;
  productDescription: string;
  customerName: string;
  customerEmailAddress: string;
  shippingTrackingNumber?: string;
  customerCommunication?: string;
  uncategorizedText?: string;
  submit: boolean; // false = stage evidence for review, true = send it to the bank now
}

export async function submitDisputeEvidence(input: EvidenceInput) {
  try {
    const evidence: Stripe.DisputeUpdateParams.Evidence = {
      product_description: input.productDescription,
      customer_name: input.customerName,
      customer_email_address: input.customerEmailAddress,
      shipping_tracking_number: input.shippingTrackingNumber,
      customer_communication: input.customerCommunication,
      uncategorized_text: input.uncategorizedText,
    };

    const dispute = await stripe.disputes.update(input.disputeId, {
      evidence,
      submit: input.submit,
    });

    return { success: true, status: dispute.status };
  } catch (err) {
    return {
      error: err instanceof Error ? err.message : "Failed to submit dispute evidence.",
    };
  }
}

What's happening here:

stripe.disputes.update() is used for both staging and submitting evidence — the submit boolean controls which one happens. submit: false (the default if you omit it) saves your evidence as a draft you can keep editing; submit: true sends it to the bank immediately and starts the review clock.
Every field inside evidence is optional — Stripe only checks that the fields required for that dispute's reason are present at the moment you actually submit. A fraudulent dispute and a product_not_received dispute expect different evidence, so don't assume one fixed field set covers every case.
Updating any field inside evidence resends the entire evidence hash for review — you're not doing a partial patch, you're replacing the evidence Stripe has on file with what you send.

⚠️ Common Mistake: Calling submit: true before you're actually ready. Unlike staged evidence, a submitted dispute response can't be edited or resubmitted with better evidence later — treat it as final, and use submit: false while you're still gathering documentation.

Step 11: Closing a Dispute You Don't Want to Fight

If you genuinely have no evidence and don't want to contest a dispute, close it explicitly instead of letting it time out:

// actions/close-dispute.ts
"use server";

import { stripe } from "@/lib/stripe/server";

export async function closeDispute(disputeId: string) {
  try {
    const dispute = await stripe.disputes.close(disputeId);
    return { success: true, status: dispute.status };
  } catch (err) {
    return { error: err instanceof Error ? err.message : "Failed to close dispute." };
  }
}

Closing a dispute is an explicit acknowledgment that you're accepting the loss — functionally similar to not responding, but it's a deliberate action in your own system rather than a deadline quietly passing.

Testing Locally with the Stripe CLI

Both refunds and disputes are testable without touching real money.

Forward Webhooks

stripe listen --forward-to localhost:3000/api/webhook

Copy the printed signing secret into .env.local as STRIPE_WEBHOOK_SECRET, then restart your dev server.

Trigger a Test Dispute

stripe trigger charge.dispute.created

This creates a real (test-mode) dispute against a test charge and fires the webhook — watch your terminal running stripe listen to confirm your handler picks it up.

Trigger a Test Refund

There's no single stripe trigger fixture for refunds, so create one directly against a test Payment Intent instead:

stripe payment_intents create --amount=2000 --currency=usd --payment-method=pm_card_visa --confirm=true
# copy the returned Payment Intent ID, then:
stripe refunds create --payment-intent=pi_xxxxx

With stripe listen running in another terminal, you'll see refund.created and refund.updated come through exactly as they would in production.

💡 Tip: stripe trigger --help lists every fixture event the CLI can simulate directly — useful for testing charge.dispute.closed or charge.dispute.funds_reinstated without waiting for a real dispute to resolve.

Production Checklist

[ ] Refund Server Actions pass an idempotencyKey, generated once per user action
[ ] UI never marks an order "refunded" before the refund.updated webhook confirms status: "succeeded"
[ ] Refund webhook events (refund.created, refund.updated, refund.failed) are handled, with charge.refunded as a fallback if you're on an older pinned API version
[ ] All five dispute events are handled: charge.dispute.created, .updated, .closed, .funds_withdrawn, .funds_reinstated
[ ] Processed webhook event IDs are stored with a unique database constraint to prevent duplicate processing
[ ] charge.dispute.created triggers an immediate alert to a real human — evidence deadlines don't wait
[ ] evidence_details.due_by is surfaced somewhere your team actually checks, not buried in Stripe's Dashboard alone
[ ] Evidence is staged (submit: false) while still being gathered, and only submitted (submit: true) once final
[ ] Live-mode webhook secret and API keys are separate from test-mode values, and never NEXT_PUBLIC_

Frequently Asked Questions

Can I refund a payment that's already been disputed?

You technically can call the API, but you shouldn't. Stripe's own guidance says a formally disputed payment should be handled through the dispute process, not a direct refund — the bank has already reimbursed the customer, so refunding on top of that risks paying them twice. The API's automated protection is narrower than "you can't refund a disputed charge" — it only catches the specific case where a dispute is filed on a charge while your refund for that charge is still pending, which fails the refund with failure_reason: "charge_for_pending_refund_disputed". Check for an open dispute yourself before issuing a refund rather than counting on the API to block it.

How long do I have to respond to a dispute?

It varies by card network and isn't a fixed number of days — always check dispute.evidence_details.due_by on the actual Dispute object rather than assuming a standard window.

What's the difference between `refund.updated` and `charge.refunded`?

refund.updated fires specifically for status changes on the Refund object itself and now covers every refund type. charge.refunded fires on the parent Charge object and is the event you'd rely on if you're pinned to an older Stripe API version that predates the expanded refund events.

Does a partial refund protect me if the customer disputes the rest?

It can help your case, but it doesn't prevent a dispute from being filed for the remaining (or even the full) amount. If that happens, submit evidence showing the partial refund you already issued as part of your response.

Can I edit dispute evidence after submitting it?

No — once you call stripe.disputes.update() with submit: true, that response is final. Keep submit: false while you're still collecting documentation, and only submit once everything is ready.

Do I need a database, or can I rely on the Stripe Dashboard alone?

For anything beyond a handful of transactions, yes. The Dashboard is fine for occasional manual lookups, but reacting to dispute deadlines and keeping order status in sync in real time requires your own webhook-driven records — the patterns in this guide.

Wrapping Up

Refunds and disputes aren't the scary edge case they're often treated as — refunds are a Server Action with an idempotency key, and disputes are a webhook listener plus an evidence-submission call. The part that actually matters is discipline: never trust a refund is complete until the webhook confirms it, and never let a dispute deadline pass silently because nobody was watching for charge.dispute.created.

From here, pair this with the Stripe webhook idempotency guide if you haven't locked down signature verification and duplicate-event handling yet, and revisit your subscription billing webhooks to make sure refund and dispute events aren't silently falling through a default case you forgot to update.

Continue Learning

Useful Resources

next-mdx-remote-client Guide for Next.js 16 (2026)

Syed Muhammad Ali — Sat, 22 Aug 2026 03:51:44 +0000

If you followed our original MDX blog setup guide, you already have a working blog powered by next-mdx-remote. There's just one problem: HashiCorp archived that repo on April 9, 2026. The package still runs fine today — nothing breaks overnight — but it's now frozen. No new features, no security patches, no fixes if a future Next.js or React release changes something it depends on.

That's not a reason to panic, but it is a reason to plan your next move. The community's answer is next-mdx-remote-client — an actively maintained fork that keeps the same mental model (compile MDX on the server, render it as React) while fixing several rough edges the original never got around to, including a proper built-in error boundary and support for export statements inside MDX on the App Router.

This guide walks through the same MDX blog setup as before, rebuilt from scratch on next-mdx-remote-client — content folder, typed data layer, custom components, syntax highlighting, and dynamic SEO metadata — so you can migrate confidently or start fresh if you're building a new Next.js 16 blog today.

Note: This guide targets the App Router using next-mdx-remote-client's React Server Component API (the /rsc subpath). If you're on the Pages Router, the package has a separate, isolated API for that too — see the FAQ at the end.

Why next-mdx-remote-client Instead of next-mdx-remote?

Both packages solve the same problem: MDX content stored outside your app folder — a content/blogs directory, a database, a CMS — rendered through one dynamic [slug] route, instead of every post being its own route file under @next/mdx.

While the original next-mdx-remote was the long-time standard for this pattern, its archiving means developers need a modern alternative. next-mdx-remote-client has emerged as the community's go-to, actively maintained drop-in replacement built specifically for the App Router. A few concrete differences that actually matter day to day:

Feature	`next-mdx-remote`	`next-mdx-remote-client`
Actively maintained	❌ Archived April 2026	✅
Built-in error handling in App Router	❌ You wrap it yourself	✅ `onError` prop
`export` statements from MDX in App Router	❌	✅
Get frontmatter + scope without a separate parse step	❌	✅ (`evaluate` function)
Utility to read frontmatter without compiling	❌	✅ `getFrontmatter`
MDX version	3	3

What "built-in error handling" actually buys you: with next-mdx-remote, a broken MDX file (a stray { in an expression, an unclosed JSX tag) throws during render, and it's on you to catch it with an ErrorBoundary. next-mdx-remote-client's MDXRemote component takes an onError prop directly, so a bad post shows a friendly fallback instead of crashing the whole page — which matters a lot the first time a typo in frontmatter takes down your blog in production.

💡 Tip: next-mdx-remote-client requires React 19.1+ and is tested against Next.js 15 and 16. If your project is still on React 18, install the @^1 tag instead — see Step 1.

A Quick Word on Security

Before writing any code: MDX compiles to executable JavaScript. That's what makes <Component /> tags work inside your Markdown, but it also means rendering MDX from a source you don't fully control (user submissions, an open CMS) can enable XSS or even remote code execution — this is true of every MDX renderer, not something specific to this package.

For a personal or team blog where you're the only one writing .mdx files, this isn't a practical concern — you already trust your own content. If you ever accept MDX from outside contributors, strip dangerous expressions at the remark stage first (the maintainer's own remark-mdx-remove-expressions plugin is built for exactly this) rather than trying to sanitize after the fact.

Prerequisites

This guide uses:

Next.js 16 with the App Router
React 19.2+
TypeScript in strict mode
Node.js 20.9+

We'll build:

MDX files stored in a content/blogs folder
A reusable getAllPosts() / getPostBySlug() data layer
Custom-styled MDX components (headings, code blocks, links, tables)
Syntax highlighting with sugar-high
remark-gfm for GitHub-flavored Markdown (tables, strikethrough, task lists)
Built-in error handling via onError
Dynamic SEO metadata and JSON-LD structured data per post

Step 1: Install Dependencies

npm install next-mdx-remote-client gray-matter remark-gfm reading-time sugar-high

Since when this matters is the whole point of this migration, be explicit about which major version you need:

# React 19 projects (the default for new Next.js 16 apps)
npm install next-mdx-remote-client@^2

# React 18 projects
npm install next-mdx-remote-client@^1

What each package does:

Package	Purpose
`next-mdx-remote-client`	Compiles and renders MDX strings as React, with built-in error handling
`gray-matter`	Parses frontmatter for the post-listing data layer
`remark-gfm`	Adds GitHub-flavored Markdown — tables, strikethrough, task lists
`reading-time`	Calculates estimated reading time from post content
`sugar-high`	Lightweight, zero-client-JS syntax highlighter for code blocks

⚠️ Common Mistake: Importing from next-mdx-remote-client directly. The package splits its App Router and Pages Router code into separate, isolated subpaths — for the App Router you always import from next-mdx-remote-client/rsc, never the bare package name. We'll use that subpath throughout this guide.

Step 2: Content Folder and Frontmatter (Unchanged)

If you're migrating from the original guide, this part doesn't change at all — next-mdx-remote-client reads the same MDX files.

content/blogs/hello-world.mdx

---
title: "Hello World: My First MDX Post"
description: "A short example post to test out the next-mdx-remote-client setup."
publishedAt: "2026-08-20"
tags: ["MDX", "Next.js"]
featured: false
---

## Hello World

This is my **first** MDX post rendered with `next-mdx-remote-client`.

- It supports Markdown
- It supports *React components*
- It even supports tables (thanks to remark-gfm)

| Feature            | Supported |
| ------------------ | --------- |
| Tables             | ✅       |
| Code blocks        | ✅       |
| Custom components  | ✅       |

Keep frontmatter field names consistent across every post (title, description, publishedAt, tags). A typo like date instead of publishedAt on one file will silently break sorting for that post, since your data layer expects an exact key.

Step 3: Build the Data Layer

This file reads every .mdx file from disk, parses frontmatter with gray-matter, and returns typed post objects for your listing page. This part still uses gray-matter on purpose — it's what powers the blog index (getAllPosts), which needs frontmatter without compiling MDX for every post just to render a list.

// lib/posts.ts
import fs from "fs";
import path from "path";
import matter from "gray-matter";
import readingTime from "reading-time";

const POSTS_PATH = path.join(process.cwd(), "content/blogs");

export type Post = {
  slug: string;
  title: string;
  description: string;
  publishedAt: string;
  updatedAt?: string;
  tags: string[];
  readingTime: string;
  content: string;
};

export function getAllPosts(): Post[] {
  const files = fs.readdirSync(POSTS_PATH);

  const posts = files.map((file) => {
    const filePath = path.join(POSTS_PATH, file);
    const fileContent = fs.readFileSync(filePath, "utf-8");

    const { data, content } = matter(fileContent);

    const slug = file.replace(/\.mdx$/, "");

    return {
      slug,
      title: data.title,
      description: data.description,
      publishedAt: data.publishedAt,
      updatedAt: data.updatedAt,
      tags: data.tags || [],
      readingTime: readingTime(content).text,
      content,
    };
  });

  return posts.sort(
    (a, b) =>
      new Date(b.publishedAt).getTime() - new Date(a.publishedAt).getTime()
  );
}

export function getPostBySlug(slug: string) {
  return getAllPosts().find((post) => post.slug === slug);
}

💡 Tip — an alternative worth knowing: next-mdx-remote-client ships its own getFrontmatter utility that reads frontmatter without compiling the MDX, using the same vfile-matter extractor internally:
import { getFrontmatter } from "next-mdx-remote-client/utils";

const { frontmatter, strippedSource } = getFrontmatter<Post>(fileContent);
It's isolated in its own subpath and costs almost nothing to import, so it's a reasonable way to drop the gray-matter dependency entirely if you're starting fresh. This guide keeps gray-matter since it's already a common dependency in most Next.js content setups and behaves identically either way.

💡 Tip: lib/posts.ts uses Node's fs module, so it only runs on the server — inside Server Components, generateStaticParams, or generateMetadata. Never import it into a "use client" component.

Step 4: Create Custom MDX Components

The component map itself is unchanged from a next-mdx-remote setup — this is standard @mdx-js/mdx behavior, and next-mdx-remote-client uses the same convention.

// mdx-components.tsx
import React, { ComponentPropsWithoutRef } from "react";
import Link from "next/link";
import { highlight } from "sugar-high";
import type { MDXComponents } from "next-mdx-remote-client/rsc";

type HeadingProps = ComponentPropsWithoutRef<"h1">;
type ParagraphProps = ComponentPropsWithoutRef<"p">;
type ListProps = ComponentPropsWithoutRef<"ul">;
type AnchorProps = ComponentPropsWithoutRef<"a">;
type BlockquoteProps = ComponentPropsWithoutRef<"blockquote">;

export const mdxComponents: MDXComponents = {
  h1: (props: HeadingProps) => (
    <h1 className="scroll-m-20 text-4xl font-bold tracking-tight lg:text-5xl" {...props} />
  ),
  h2: (props: HeadingProps) => (
    <h2 className="scroll-m-20 mt-16 pb-2 text-3xl font-semibold tracking-tight" {...props} />
  ),
  h3: (props: HeadingProps) => (
    <h3 className="scroll-m-20 mt-12 text-2xl font-semibold tracking-tight" {...props} />
  ),
  p: (props: ParagraphProps) => (
    <p className="text-gray-800 dark:text-zinc-300" {...props} />
  ),
  ul: (props: ListProps) => (
    <ul className="text-gray-800 dark:text-zinc-300 list-disc pl-5 space-y-1" {...props} />
  ),
  a: ({ href, children, ...props }: AnchorProps) => {
    const className = "text-blue-500 hover:text-blue-700";

    if (href?.startsWith("/")) {
      return (
        <Link href={href} className={className} {...props}>
          {children}
        </Link>
      );
    }

    return (
      <a href={href} target="_blank" rel="noopener noreferrer" className={className} {...props}>
        {children}
      </a>
    );
  },
  code: ({ children, ...props }: ComponentPropsWithoutRef<"code">) => {
    const codeHTML = highlight(String(children));
    return <code dangerouslySetInnerHTML={{ __html: codeHTML }} {...props} />;
  },
  blockquote: (props: BlockquoteProps) => (
    <blockquote className="ml-[0.075em] border-l-3 border-green-400 pl-4 text-gray-700" {...props} />
  ),
};

What's different here from a next-mdx-remote setup: the MDXComponents type now comes from next-mdx-remote-client/rsc instead of mdx/types — the package re-exports it so you don't need a separate import. Everything else, including the special wrapper key if you want to wrap MDX content in a container element, works exactly the same way.

Step 5: Build the Dynamic Blog Route

This is where the actual migration happens. Swap the import source and add the onError prop — the rest of the route looks familiar if you've built this with next-mdx-remote before.

// app/blog/[slug]/page.tsx
import { Suspense } from "react";
import { notFound } from "next/navigation";
import { MDXRemote, type MDXRemoteOptions } from "next-mdx-remote-client/rsc";
import remarkGfm from "remark-gfm";
import { getAllPosts, getPostBySlug } from "@/lib/posts";
import { mdxComponents } from "@/mdx-components";
import ErrorComponent from "@/components/error-component";

interface BlogPostPageProps {
  params: Promise<{ slug: string }>;
}

// Pre-renders every post at build time (Static Site Generation)
export async function generateStaticParams() {
  const posts = getAllPosts();
  return posts.map((post) => ({ slug: post.slug }));
}

export async function generateMetadata({ params }: BlogPostPageProps) {
  const { slug } = await params;
  const post = getPostBySlug(slug);

  if (!post) return {};

  return {
    title: post.title,
    description: post.description,
  };
}

const mdxOptions: MDXRemoteOptions = {
  mdxOptions: {
    remarkPlugins: [remarkGfm],
  },
};

export default async function BlogPostPage({ params }: BlogPostPageProps) {
  const { slug } = await params;
  const post = getPostBySlug(slug);

  if (!post) {
    notFound();
  }

  return (
    <article className="prose dark:prose-invert mx-auto">
      <h1>{post.title}</h1>

      <Suspense fallback={<p>Loading post…</p>}>
        <MDXRemote
          source={post.content}
          components={mdxComponents}
          options={mdxOptions}
          onError={ErrorComponent}
        />
      </Suspense>
    </article>
  );
}

Create Error component

// components/error-component.tsx

'use client'

export default function ErrorComponent({ error }: { error: unknown | Error }) {
    return (
        <div className="rounded-xl border border-destructive/30 bg-destructive/5 p-4 text-sm text-destructive">
            <pre>
                <code>
                    {typeof error === "string"
                        ? error
                        : error instanceof Error
                            ? error.message
                            : String(error)}
                </code>
            </pre>
        </div>
  );
}

What's actually new compared to next-mdx-remote:

import { MDXRemote } from "next-mdx-remote-client/rsc" — the App Router entry point. Importing from the bare package name here would pull in the Pages Router code path instead, which won't work.
<Suspense> is required, not optional. MDXRemote is an async Server Component under the hood — it returns a Promise<React.JSX.Element> — so it needs a Suspense boundary the same way any other async Server Component does.
onError={ErrorComponent} is the headline feature from earlier. If this specific post's MDX fails to compile — a syntax error like an unclosed tag, or a bad frontmatter parse — MDXRemote catches it internally and renders ErrorComponent in its place, instead of taking down the whole page.
options.mdxOptions.remarkPlugins still works exactly the way next-mdx-remote did — remark-gfm plugs in the same way for tables and GFM syntax.

⚠️ Common Mistake: Forgetting the <Suspense> wrapper. Since MDXRemote is async, rendering it directly without a Suspense boundary will throw a build error telling you an async component needs one — this is a hard requirement of the package, not a style suggestion.

💡 Tip: Notice onError catches compile/render errors caught by the package's internal handling, but the README is explicit that evaluating the compiled module itself doesn't throw except syntax errors — some render-time errors from a broken custom component can still escape and need a real React <ErrorBoundary> around your route if you want to be fully defensive. For a typical blog where you control every MDX file, onError alone covers the realistic failure cases (a bad frontmatter reference, a malformed table, an unclosed tag).

If you want to deep dive into Error Handling in Next.js, I've full guide covering this topic here.

Step 6: Want Frontmatter and Scope Inside JSX? Use `evaluate` Instead

The MDXRemote component above is enough if you only need frontmatter and custom data inside the MDX body (e.g. # {frontmatter.title} written directly in the .mdx file). If you need that data outside the MDX, in your page's own JSX — for a byline, a reading-time badge, a table of contents component — reach for the lower-level evaluate function instead.

Update lib/posts.ts

// lib/posts.ts
export const getSource = async (filename: string): Promise<string | undefined> => {
    const sourcePath = path.join(POSTS_PATH, filename);
    if (!fs.existsSync(sourcePath)) return;
    return await fs.promises.readFile(sourcePath, "utf8");
};

// app/blog/[slug]/page.tsx (alternative using evaluate)
import { Suspense } from "react";
import { evaluate, type EvaluateOptions } from "next-mdx-remote-client/rsc";
import remarkGfm from "remark-gfm";
import { getSource } from "@/lib/posts";
import { mdxComponents } from "@/mdx-components";
import ErrorComponent from "@/components/error-component";

interface BlogPostPageProps {
    params: Promise<{ slug: string }>;
}

type Frontmatter = {
  title: string;
  description: string;
};

const mdxOptions: MDXRemoteOptions = {
    parseFrontmatter: true,
    mdxOptions: {
        remarkPlugins: [remarkGfm],
    },
};

export default async function BlogPostPage({ params }: BlogPostPageProps) {
    const { slug } = await params;
    const source = await getSource(`${slug}.mdx`)!;

    if (!source) return <ErrorComponent error="The source could not found!" />;

  const { content, frontmatter, error } = await evaluate<Frontmatter>({
    source,
    options: mdxOptions,
    components: mdxComponents,
  });

    if (error) return <ErrorComponent error={error} />;

  return (
    <article className="prose dark:prose-invert mx-auto">
      <h1>{frontmatter.title}</h1>
            <Suspense fallback={<p>Loading post…</p>}>
                {content}
            </Suspense>
    </article>
  );
}

What's happening here: evaluate returns { content, mod, frontmatter, scope, error } all at once — content is the compiled MDX JSX (still needs its own <Suspense>), frontmatter is typed and available immediately for use in your surrounding JSX, and error is a plain object you check yourself instead of a component prop. This is the tool to reach for whenever you need frontmatter or a table-of-contents object before the MDX renders, not just inside it — the MDXRemote component genuinely can't do this on the App Router, since it doesn't hand you the frontmatter as a return value at all.

💡 Tip: Passing parseFrontmatter: true here means evaluate extracts frontmatter itself — you could skip gray-matter entirely for a page that only needs a single post. This guide's lib/posts.ts still uses gray-matter separately because the blog index page needs frontmatter for every post at once, without compiling every post's MDX just to list titles.

Step 7: Add JSON-LD Structured Data (Optional, but Great for SEO)

Unchanged from the original setup — this is a Next.js <Script> tag, not something the MDX package touches.

// app/blog/[slug]/page.tsx (addition)
import Script from "next/script";

<Script
  type="application/ld+json"
  dangerouslySetInnerHTML={{
    __html: JSON.stringify({
      "@context": "https://schema.org",
      "@type": "BlogPosting",
      headline: post.title,
      description: post.description,
      datePublished: post.publishedAt,
      author: { "@type": "Person", name: "Your Name" },
    }),
  }}
/>;

Step 8: Style Blog Content with Tailwind Typography

Also unchanged — MDX content renders as plain, unstyled HTML by default regardless of which remote-MDX package compiled it.

npm install @tailwindcss/typography

/* app/globals.css */
@import "tailwindcss";

@plugin "@tailwindcss/typography";

:root {
  --sh-class: #7aa2f7;
  --sh-sign: #89ddff;
  --sh-string: #9ece6a;
  --sh-keyword: #bb9af7;
  --sh-comment: #acacac;
  --sh-jsxliterals: #7aa2f7;
  --sh-property: #73daca;
  --sh-entity: #e0af68;
  --sh-identifier: #fff;
}

@layer base {
  code:not(pre code) {
    background-color: var(--color-gray-100);
  }

  code:not(pre code) span {
    font-weight: 600;
    color: black !important;
  }

  table {
    display: block;
    max-width: fit-content;
    overflow-x: auto;
    white-space: nowrap;
    text-align: left;
  }
}

Migrating an Existing next-mdx-remote Setup: Checklist

If you already have the original guide's setup running in production, here's the exact diff:

[ ] npm uninstall next-mdx-remote and npm install next-mdx-remote-client@^2 (or @^1 on React 18)
[ ] Remove transpilePackages: ['next-mdx-remote'] from next.config.mjs if present — it's not needed for next-mdx-remote-client
[ ] Change import { MDXRemote } from "next-mdx-remote/rsc" to import { MDXRemote } from "next-mdx-remote-client/rsc"
[ ] Change options={{ mdxOptions: { remarkPlugins: [remarkGfm] } }} to a typed MDXRemoteOptions object (optional, but gets you autocomplete)
[ ] Add an onError component and pass it as a prop — you're no longer required to hand-roll this yourself
[ ] Confirm your route already wraps <MDXRemote /> in <Suspense> — next-mdx-remote's RSC component was also async, so this requirement doesn't actually change
[ ] mdx-components.tsx, lib/posts.ts, your .mdx content files, and your Tailwind Typography setup all need zero changes

For most blogs, this is a genuinely small migration — the package was designed as a drop-in-shaped replacement, not a rewrite.

Frequently Asked Questions

Is next-mdx-remote-client a fork or a completely separate project?

It's a from-scratch package built independently in 2024, in the spirit of @mdx-js/mdx, rather than a literal code fork — but it's positioned and documented as a direct alternative to next-mdx-remote, with a published migration guide for exactly this switch.

Do I need to change my .mdx content files at all?

No. next-mdx-remote-client compiles the same MDX syntax, reads the same frontmatter format, and works with the same custom component map. The migration is entirely in your route and import statements, not your content.

Can I still use next-mdx-remote/utils-style frontmatter parsing without gray-matter?

Yes — use getFrontmatter from next-mdx-remote-client/utils, shown in Step 3. It's isolated in its own subpath specifically so it costs almost nothing to import, and the maintainer notes it works fine even if you're still on plain next-mdx-remote elsewhere in your app.

What's the difference between MDXRemote and evaluate?

MDXRemote is the simpler option when you only need frontmatter and scope data inside the MDX body itself. evaluate is lower-level and returns frontmatter, scope, and exported mod data directly to your page's JSX — reach for it when a byline, reading-time badge, or table-of-contents component outside the MDX needs that data. See Step 6.

Does this work with the Pages Router too?

Yes, but through a completely separate, isolated API — serialize (server-side, in getStaticProps), plus hydrate and MDXClient (client-side) — imported from next-mdx-remote-client/serialize and next-mdx-remote-client/csr rather than /rsc. The App Router and Pages Router code paths don't share internals.

Is next-mdx-remote actually broken right now?

No — HashiCorp archived the repository, meaning it's read-only with no further commits, but the last published version (6.0.0) still installs and runs normally today. Nothing forces an immediate migration. The reason to move is that any future Next.js, React, or @mdx-js/mdx change that breaks compatibility will never get a fix from the original package.

Wrapping Up

The move from next-mdx-remote to next-mdx-remote-client is a narrow, mechanical change for most blogs: swap the package, swap one import path, add an onError handler, and everything else — your content folder, your data layer, your custom components, your Tailwind Typography setup — keeps working exactly as it did. What you get in exchange is a package that's still receiving updates, plus a real error boundary for MDX rendering that the original never shipped.

If you're starting a brand-new Next.js 16 blog today rather than migrating one, just start here directly — there's no reason to build on the archived package first.

Useful Resources

Continue Learning

Free Developer Tools

Meta Tag Generator for Next.js & HTML — generate SEO meta tags, Open Graph tags, Twitter Cards, and JSON-LD instantly for each post.
JSON-LD Generator for Next.js & HTML — generate BlogPosting structured data checked live against Google's Rich Results requirements.

📦 Source Code: View on GitHub

Server vs Client Components in Next.js 16 (2026 Guide)

Syed Muhammad Ali — Mon, 10 Aug 2026 04:01:25 +0000

You add "use client" to the top of a file, TypeScript stops complaining, and everything just... works. So you start adding it everywhere — every component, just in case. A few weeks later your bundle size has crept up, your pages feel sluggish, and you're not sure why, because "it's just React, right?"

It's not just React. The App Router split every component into one of two worlds — Server Components and Client Components — and that split is the single biggest architectural decision in a modern Next.js app. Get it right and you ship less JavaScript, load faster, and keep secrets like API keys off the browser entirely. Get it wrong and you end up with a Next.js app that behaves like a slower, more confusing version of a plain React SPA.

By the end of this guide, you'll know exactly what each type of component can and can't do, how they talk to each other, and — most importantly — a simple decision framework so you stop guessing where "use client" belongs.

The Quick Answer

If you only remember one rule: start every component as a Server Component, and only add "use client" when you hit something that genuinely requires the browser — state, effects, event handlers, or browser-only APIs.

Need	Use
Fetching data from a database or API	Server Component
Reading environment variables / secrets	Server Component
`useState`, `useReducer`, `useEffect`	Client Component
`onClick`, `onChange`, any event handler	Client Component
`window`, `localStorage`, `document`	Client Component
Context providers (theme, auth state)	Client Component
Large third-party UI libraries (charts, rich text editors)	Client Component
Static or data-driven markup with no interactivity	Server Component

Keep that table in mind — everything below is really just explaining why it's true.

Why This Split Exists

Before the App Router, every component in a Next.js (or Create React App) project shipped to the browser as JavaScript, got hydrated, and ran client-side — even if it never did anything interactive. A blog post's paragraph tags didn't need useState, but they got bundled and hydrated like they did.

Server Components (RSCs) fix that. They render entirely on the server, and Next.js sends the browser the rendered result through the React Server Component Payload. Client Components are represented by references to their JavaScript so React can hydrate the interactive parts in the browser.

💡 Think of it like this: a Server Component is a chef cooking in the kitchen — you never see the knives, the raw ingredients, or the mess. You just get the finished plate (HTML). A Client Component is more like a tabletop grill brought out to your table — it needs its own equipment (JavaScript) shipped out to you so you can interact with it directly.

This matters for three concrete reasons:

Smaller bundles. Every component that doesn't need interactivity costs zero client-side JavaScript.
Safer secrets. Server Components can read environment variables, call your database, or hit an internal API directly — that code never reaches the browser, so there's nothing to leak in dev tools.
Faster data fetching. A Server Component can await a database call directly in the component body — no client-side loading spinner, no waterfall of useEffect → fetch → re-render.

Server Components: The Default

In the App Router, every component is a Server Component unless you say otherwise. No directive, no import, nothing special — just a normal .tsx file.

// app/products/page.tsx
import { getProducts } from "@/lib/products";

const ProductsPage = async () => {
  const products = await getProducts();

  return (
    <ul className="grid grid-cols-2 gap-4">
      {products.map((product) => (
        <li key={product.id} className="rounded-lg border p-4">
          <h2 className="font-semibold">{product.name}</h2>
          <p className="text-muted-foreground">${product.price}</p>
        </li>
      ))}
    </ul>
  );
};

export default ProductsPage;

What's happening here: ProductsPage is async, and it awaits getProducts() directly inside the component — something you could never do in a regular React component. Next.js runs this on the server, resolves the data, renders the final HTML, and streams that HTML to the browser. There's no client-side fetch, no loading state to manage manually, and none of getProducts()'s implementation (database credentials, query logic) ever ships to the browser.

What Server Components Are Good At

Data fetching close to the source — call your database or a private API directly, with full access to server-only environment variables.
Keeping secrets server-side — an API key used inside a Server Component never appears in the browser's network tab or JavaScript bundle.
Reducing client JavaScript — a Server Component's code, and everything it imports, is stripped from the client bundle entirely.

What Server Components Can't Do

No useState, useReducer, or any React hook that depends on the client render lifecycle.
No event handlers — onClick, onChange, onSubmit handlers all require the browser's event system.
No useEffect, window, document, or any browser-only API — none of that exists on the server.
No React Context consumption via useContext (though a Server Component can be rendered inside a Client Component's context provider — more on that below).

⚠️ Common Mistake: Trying to add an onClick to a Server Component and getting a build error like "Event handlers cannot be passed to Client Component props." This isn't a bug — it's Next.js telling you this piece of UI needs to become a Client Component.

Client Components: Opting Into the Browser

The moment a component needs state, an event handler, or a browser API, you mark it explicitly with the "use client" directive at the very top of the file — before any imports.

// components/like-button.tsx
"use client";

import { useState } from "react";

interface LikeButtonProps {
  initialLikes: number;
}

export const LikeButton = ({ initialLikes }: LikeButtonProps) => {
  const [data, setData] = useState({ likes: initialLikes, liked: false });

  const handleClick = () => {
    setData((prev) => ({ likes: prev.liked ? prev.likes - 1 : prev.likes + 1, liked: !prev.liked  }))
  };

  return (
    <button
      onClick={handleClick}
      className="flex items-center gap-1.5 rounded-full border px-3 py-1.5 text-sm"
    >
      {data.liked ? "❤️" : "🤍"} {data.likes}
    </button>
  );
};

What's happening here: "use client" tells Next.js "this file, and everything it exports, needs to run in the browser too." The component still renders on the server for the first paint (Next.js server-renders Client Components as well, for fast initial HTML), but its JavaScript is also sent to the browser so React can hydrate it — attach event listeners and make useState actually work after the page loads.

💡 Tip: "use client" doesn't mean "this only runs in the browser." It means "this component needs the browser eventually." Next.js still renders it on the server first for a fast initial page load — that's what makes the App Router different from a plain client-side React app.

What Client Components Are Good At

Anything interactive: forms, toggles, dropdowns, modals, drag-and-drop.
State that changes in response to user input.
Browser-only APIs — localStorage, navigator.geolocation, IntersectionObserver.
Real-time updates — WebSocket connections, polling, live subscriptions.
Third-party libraries that rely on React hooks internally (most chart libraries, rich text editors, and animation libraries fall into this category).

How They Actually Work Together

This is the part that trips most beginners up: Server and Client Components aren't two separate apps — they're one component tree, and you compose them together. The trick is understanding the direction data and imports are allowed to flow.

Rule 1: Server Components Can Import Client Components

This is the easy, common direction. A Server Component (like a page) can freely render a Client Component as a normal child.

// app/blog/[slug]/page.tsx
import { getPostBySlug } from "@/lib/posts";
import { LikeButton } from "@/components/like-button";

interface Props {
  params: Promise<{ slug: string }>;
}

const BlogPostPage = async ({ params }: Props) => {
  const { slug } = await params;
  const post = await getPostBySlug(slug);

  return (
    <article>
      <h1>{post.title}</h1>
      <div>{post.content}</div>

      {/* A Client Component rendered inside a Server Component — totally normal */}
      <LikeButton initialLikes={post.likeCount} />
    </article>
  );
};

export default BlogPostPage;

What's happening here: BlogPostPage stays a Server Component — it fetches post directly from the database with no client-side JavaScript for that part. LikeButton is the one interactive piece, so only its JavaScript ships to the browser. Everything else on the page — the title, the article body — costs nothing.

⚠️ Common Mistake: Adding "use client" to the whole page just because one small piece (like a like button) needs interactivity. That drags every Server Component this page imports into the client bundle too. Keep the directive on the smallest possible component.

Rule 2: Client Components Can't Import Server Components Directly

This is the one that catches people off guard. Once you're inside a "use client" file, you establish a boundary; everything imported into that file automatically becomes part of the client bundle and runs in the browser. If a Server Component containing backend-specific logic (like direct database queries or API keys) is directly imported, it will either crash the build or fail at runtime because the browser environment lacks server-side capabilities.

// ❌ This will not work as expected
"use client";

import { UserProfile } from "@/components/user-profile"; // a Server Component

export const Sidebar = () => {
  return (
    <aside>
      <UserProfile /> {/* This gets converted into a Client Component too */}
    </aside>
  );
};

If you attempt to import a Server Component directly into a Client Component, it forces the Server Component to transform into a Client Component.

Rule 3: The Fix — Pass Server Components as `children`

Instead of importing a Server Component inside a Client Component, render the Server Component in a parent Server Component, and pass it down as children (or any prop) to the Client Component.

// components/theme-provider.tsx
"use client";

import { createContext, useState, type ReactNode } from "react";

export const ThemeContext = createContext<"light" | "dark">("light");

interface ThemeProviderProps {
  children: ReactNode;
}

export const ThemeProvider = ({ children }: ThemeProviderProps) => {
  const [theme] = useState<"light" | "dark">("light");

  return (
    <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>
  );
};

// app/layout.tsx
import { ThemeProvider } from "@/components/theme-provider";
import { UserProfile } from "@/components/user-profile"; // still a Server Component

const RootLayout = ({ children }: { children: React.ReactNode }) => {
  return (
    <html lang="en">
      <body>
        <ThemeProvider>
          {/* UserProfile is rendered by the (server) RootLayout, then
              *slotted into* the Client Component as children. It never
              becomes a Client Component itself. */}
          <UserProfile />
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
};

export default RootLayout;

What's happening here: RootLayout is a Server Component, so it's allowed to render UserProfile (also a Server Component) normally. It then hands the already-rendered result to ThemeProvider as children. From ThemeProvider's point of view, children is just a slot — it doesn't care what rendered it, so UserProfile never has to become a Client Component. This "children as a slot" pattern is the standard fix any time you need to wrap Server Component content in a Client Component like a context provider, a modal, or an animated wrapper.

Passing Data Between Server and Client Components

Props passed from a Server Component to a Client Component must be serializable by React's Server Component protocol. Plain data such as strings, numbers, booleans, arrays, and objects is the safest approach. Functions generally cannot cross the boundary, except for supported Server Actions — see below.

// app/dashboard/page.tsx
import { getUser } from "@/lib/user";
import { ProfileCard } from "@/components/profile-card";

const DashboardPage = async () => {
  const user = await getUser();

  return <ProfileCard name={user.name} email={user.email} />;
};

export default DashboardPage;

// components/profile-card.tsx
"use client";

import { useState } from "react";

interface ProfileCardProps {
  name: string;
  email: string;
}

export const ProfileCard = ({ name, email }: ProfileCardProps) => {
  const [expanded, setExpanded] = useState(false);

  return (
    <div
      onClick={() => setExpanded((prev) => !prev)}
      className="cursor-pointer rounded-lg border p-4"
    >
      <p className="font-medium">{name}</p>
      {expanded && <p className="text-sm text-muted-foreground">{email}</p>}
    </div>
  );
};

What's happening here: DashboardPage fetches user on the server and passes only the plain string fields it needs (name, email) down as props — not the whole user object, and definitely not a database client or ORM instance. ProfileCard receives those as regular props and manages its own expanded state locally.

Passing Functions: Server Actions Are the Exception

Regular functions can't cross from server to client as props — but Server Actions (functions marked with "use server") can, because Next.js turns them into a callable reference instead of trying to serialize the function itself.

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

export const createPost = async (formData: FormData) => {
  const title = formData.get("title") as string;

  // await db.post.create({ data: { title } });
};

// app/posts/new/page.tsx
import { createPost } from "@/actions/posts";
import { PostForm } from "@/components/post-form";

const NewPostPage = () => {
  return <PostForm action={createPost} />;
};

export default NewPostPage;

// components/post-form.tsx
"use client";

interface PostFormProps {
  action: (formData: FormData) => Promise<void>;
}

export const PostForm = ({ action }: PostFormProps) => {
  return (
    <form action={action} className="flex flex-col gap-3">
      <input
        name="title"
        placeholder="Post title"
        className="rounded-lg border px-3 py-2"
      />
      <button type="submit" className="rounded-lg bg-primary px-4 py-2 text-white">
        Create
      </button>
    </form>
  );
};

What's happening here: createPost is a Server Action — Next.js compiles it into a secure, callable reference rather than shipping its actual implementation to the browser. PostForm receives it as a prop and passes it straight to the native <form action={...}> attribute, so submitting the form runs createPost on the server without you writing a single fetch call or API route.

💡 Tip: Server Actions run on the server, but you should still authenticate the user, authorize the requested operation, and validate all input inside the action.

Common Mistakes to Avoid

⚠️ Mistake 1: Marking the entire page "use client". This is the single biggest anti-pattern. It turns every Server Component that page imports into client-shipped JavaScript, even ones that never needed to be. Push "use client" down to the smallest interactive leaf component instead.

⚠️ Mistake 2: Importing server-only code (a database client, a Node.js-only package) into a file that's part of a Client Component's import tree. Use the server-only package to catch this at build time — importing it at the top of a server-only file throws a build error the moment a Client Component accidentally pulls it in.

// lib/db.ts
import "server-only"; // throws a build error if this file is ever imported client-side

import { createClient } from "@supabase/supabase-js";

export const db = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

⚠️ Mistake 3: Passing non-serializable props (a function that isn't a Server Action, a class instance, a Map/Set) from a Server Component into a Client Component. Next.js will throw a clear error at build or runtime — convert the data to a plain object, array, or primitive first.

⚠️ Mistake 4: Wrapping a large chunk of static UI in a Client Component just because it sits next to something interactive. Only the interactive piece needs "use client" — everything around it can, and should, stay a Server Component.

A Practical Example: Product Page With a Cart Button

Here's a realistic page that mixes both, following the composition pattern from earlier.

// app/products/[id]/page.tsx
import { getProduct } from "@/lib/products";
import { AddToCartButton } from "@/components/add-to-cart-button";

interface Props {
  params: Promise<{ id: string }>;
}

const ProductPage = async ({ params }: Props) => {
  const { id } = await params;
  const product = await getProduct(id);

  return (
    <div className="mx-auto max-w-2xl space-y-4 p-6">
      <h1 className="text-2xl font-semibold">{product.name}</h1>
      <p className="text-muted-foreground">{product.description}</p>
      <p className="text-xl font-bold">${product.price}</p>

      {/* Only this button ships JavaScript to the browser */}
      <AddToCartButton productId={product.id} price={product.price} />
    </div>
  );
};

export default ProductPage;

// components/add-to-cart-button.tsx
"use client";

import { useState } from "react";

interface AddToCartButtonProps {
  productId: string;
  price: number;
}

export const AddToCartButton = ({ productId, price }: AddToCartButtonProps) => {
  const [adding, setAdding] = useState(false);

  const handleAddToCart = async () => {
    setAdding(true);
    await fetch("/api/cart", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ productId, price }),
    });
    setAdding(false);
  };

  return (
    <button
      onClick={handleAddToCart}
      disabled={adding}
      className="rounded-lg bg-primary px-5 py-2.5 text-white disabled:opacity-50"
    >
      {adding ? "Adding..." : "Add to Cart"}
    </button>
  );
};

What's happening here: the product name, description, and price are all static HTML by the time they reach the browser — zero JavaScript for any of it. AddToCartButton is the only part of this page that ships client-side JavaScript, and it's scoped to exactly the props it needs (productId, price), not the entire product object.

Frequently Asked Questions

Do Server Components run on every request?

Not necessarily — it depends on how the page is rendered. A Server Component in a statically generated page (SSG) runs once at build time. One using dynamic data (like cookies() or an uncached fetch) runs fresh on every request. Next.js Rendering Strategies Explained covers this in more depth.

Can I use `useContext` inside a Server Component?

No — useContext, along with every other React hook, requires the client render lifecycle. But a Server Component can be rendered as children inside a Client Component that provides context, which is exactly the composition pattern shown above.

Is `"use client"` the same as the old Pages Router's client-side rendering?

Not quite. A Client Component still gets server-rendered first for the initial HTML, then hydrated in the browser. It's not a pure client-side render the way a traditional single-page app works — you get the best of both: fast first paint and interactivity after hydration.

Why does my Client Component still work fine with a database import?

You might not have hit the boundary yet — Next.js only errors out once that server-only code is actually part of the browser's bundle, which can depend on your import chain. Don't rely on it silently working; add the server-only package to any file that should never reach the client, so the mistake fails loudly at build time instead of leaking secrets in production.

Should layouts be Server or Client Components?

Default to Server Components for layouts — they usually just arrange other components and rarely need state themselves. If your layout needs a client-side provider (theme, auth context), extract just that provider into its own "use client" file and wrap children with it, rather than marking the whole layout as a Client Component.

Does marking a component `"use client"` also make its children Client Components?

"use client" defines a Client Component boundary. The component and the modules it imports are treated as part of the client module graph. However, components passed to it as children or other props aren't automatically converted into Client Components.

Wrapping Up

The Server/Client Component split isn't extra complexity for its own sake — it's what lets a Next.js 16 app ship less JavaScript, keep secrets off the browser, and fetch data without a client-side waterfall. The mental model is simple once it clicks: default to Server Components, reach for "use client" only at the smallest interactive leaf, and use the children pattern whenever a Client Component needs to wrap Server Component content.

From here, a natural next step is pairing this with Next.js Rendering Strategies Explained to see how Server Components fit into SSR, SSG, ISR, and Cache Components — or Error Handling in Next.js 16 to see how error.tsx boundaries interact with both component types.

Continue Learning

Session vs JWT: Which Should You Use in Next.js 16?

Syed Muhammad Ali — Sun, 09 Aug 2026 05:45:22 +0000

You're building a login flow in Next.js 16, and you hit the question every auth tutorial glosses over: should the logged-in state live in a session or a JWT? Half the guides you find use one, half use the other, and almost none of them tell you why — or what breaks if you pick wrong.

Here's the annoying part: both approaches look nearly identical from the outside. A cookie gets set, the user stays logged in, everyone's happy. The difference only shows up later — when you need to log a user out of every device instantly, when your app scales past one server, or when you're debugging why a "revoked" user can still hit your API for another six days.

By the end of this guide, you'll know exactly how sessions and JWTs work under the hood, see real, working code for both in Next.js 16 — using jose, Server Actions, and proxy.ts — and know which one actually fits your project instead of copying whatever the last tutorial you read happened to use.

Why This Is Tricky

Most explanations of "session vs JWT" get stuck comparing them as if they're two totally separate technologies. They're not. In both approaches, the browser stores a cookie. The real difference is what that cookie contains, and where the source of truth lives:

Session-based auth: the cookie holds a random ID. The actual user data lives in your database. Every request that needs to know "who is this?" looks it up server-side.
JWT-based auth: the cookie holds the user data itself, cryptographically signed. Your server can verify it's untampered without ever touching a database.

That one distinction — lookup vs. self-contained — is what drives every tradeoff in this post: revocation, scaling, latency, and how much you need to trust the cookie itself.

💡 Tip: If you've used Auth.js (NextAuth v5), you've already used both without necessarily noticing — its session: { strategy: "jwt" } and session: { strategy: "database" } options are exactly this same choice, just configured for you.

Prerequisites

This guide uses:

Next.js 16 with the App Router
TypeScript in strict mode
React Compiler enabled (no manual useMemo/useCallback needed)
Tailwind CSS for the (minimal) UI examples

You don't need a real database to follow along — the JWT section has zero dependencies, and the session section uses a generic db client you can swap for Postgres, Supabase, or whatever you're already using.

How Sessions Work

💡 Think of it like: a coat check ticket. The ticket itself is just a number — it means nothing on its own. The actual coat (your user data) stays with the attendant (your database). Lose the ticket, and the attendant can also just... stop honoring it. Instantly.

User logs in with the right credentials.
Your server generates a random token, stores it in a sessions table alongside the user's ID and an expiry, and sends that token back as an httpOnly cookie.
On every request, your server takes the cookie value, looks it up in the database, and either finds a valid session or doesn't.
To log someone out — including forcibly, from your side — you delete the row. Done. The cookie is now worthless.

The tradeoff: every authenticated request costs a database round trip (unless you cache it), but you get instant, guaranteed revocation.

How JWTs Work

💡 Think of it like: a sealed, signed letter. Anyone can read what's inside once it's opened, but nobody can forge your signature or quietly edit the contents without breaking the seal. The letter is self-sufficient — you don't need to call anyone to confirm it's real, just check the seal.

User logs in with the right credentials.
Your server creates a token containing the user's ID (and whatever else you want) and signs it with a secret key.
On every request, your server checks the signature against that same secret. If it matches, the data inside is trusted — no database lookup required.
To log someone out, you delete the cookie client-side. But if someone already has a copy of that token, it's still valid — and still verifiable — until it naturally expires. There's no built-in way to say "actually, ignore this one."

The tradeoff: verification is fast and needs no database, but you give up the ability to instantly kill a single session without extra machinery.

⚠️ Common Mistake: Calling a JWT stored in a cookie a "session" and assuming it behaves like one. It doesn't — a JWT has no server-side record at all unless you deliberately build one (see the revocation section below). If your mental model is "session," you'll be surprised the first time you try to force-logout a user and nothing happens.

⚠️ Cookie size limits: browsers cap a single cookie at roughly 4KB, and most reverse proxies (Nginx, Cloudflare) reject requests once the total header size gets much past 8KB. A session-ID cookie is always tiny — it's just a random string. A JWT cookie grows with every claim you cram into the payload (roles, permissions, profile fields). Stuff enough into it and the cookie silently fails to set, or your CDN starts 400-ing requests, with no obvious error pointing back at "your JWT got too big." Keep JWT payloads minimal — an ID and maybe a role, not a serialized user object.

Step 1: Set Up the Shared Pieces

Both approaches need somewhere to keep a signing secret. Add one to your environment file:

# .env.local
SESSION_SECRET=your-long-random-secret-here

Generate a strong value instead of typing something memorable:

node -e "console.log(crypto.randomBytes(32).toString('hex'))"

⚠️ Common Mistake: Committing SESSION_SECRET to git, or reusing your .env.local value in production. Treat it exactly like a database password — if it leaks, an attacker can forge valid sessions for any user, for either approach below.

Step 2: Build JWT-Based Auth with `jose`

jose is the standard library for signing and verifying JWTs in an Edge-compatible way — it uses the Web Crypto API instead of Node's crypto module, so it works identically in Server Actions, Route Handlers, and proxy.ts.

npm install jose

Create the sign/verify helpers

// lib/jwt/session.ts
import "server-only";
import { SignJWT, jwtVerify } from "jose";

const secretKey = process.env.SESSION_SECRET;
const encodedKey = new TextEncoder().encode(secretKey);

export async function encrypt(userId: string, expiresAt: Date) {
  return new SignJWT({})
    .setProtectedHeader({ alg: "HS256" })
    .setSubject(userId) // sub — who this token belongs to
    .setIssuedAt() // iat — when it was issued
    .setExpirationTime(expiresAt) // exp — when it stops being valid
    .sign(encodedKey);
}

export async function decrypt(token: string | undefined = "") {
  try {
    const { payload } = await jwtVerify(token, encodedKey, {
      algorithms: ["HS256"],
    });
    return payload; // payload.sub is the userId; iat/exp are unix seconds
  } catch {
    // Invalid signature, tampered payload, or expired token
    return null;
  }
}

What's happening here: instead of a custom userId field, this uses the standard, registered JWT claims — sub (subject, via .setSubject()), iat (issued-at, via .setIssuedAt()), and exp (expiry, via .setExpirationTime()). These three are part of the JWT spec itself, not a jose-specific convention, so any JWT library — in any language — knows how to read them. jwtVerify automatically checks exp and rejects an expired token before your code ever sees the payload, so you never write manual date comparisons.

⚠️ Signing is not encryption. SignJWT — despite this file calling the wrapper functions encrypt/decrypt for readability — does not hide the payload. A JWT's contents are only base64url-encoded, not encrypted, so anyone who intercepts the cookie (or just opens DevTools → Application → Cookies) can decode and read sub, iat, and exp in plain text. What the signature guarantees is that the payload wasn't tampered with — change one character and jwtVerify rejects it. Never put anything genuinely secret (passwords, tokens for other services, PII you wouldn't want exposed) inside a signed JWT. If you actually need to hide the contents too, that's a different primitive — JWE — which jose supports separately via EncryptJWT/jwtDecrypt.

💡 Do you still need setExpirationTime if you also track expiry elsewhere? No — and the version above deliberately avoids the redundancy. Compute the expiry date once, and hand that same Date to both setExpirationTime() (for the JWT's own exp claim) and the cookie's expires option, as shown in the next step. Two separately-computed "7 days from now" values can drift apart by milliseconds and give you two conflicting sources of truth for the same thing — pick one.

Create the session cookie on login

// lib/jwt/actions.ts
"use server";

import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { encrypt } from "./session";

export async function createSession(userId: string) {
  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);
  const session = await encrypt(userId, expiresAt); // same Date used for exp and the cookie
  const cookieStore = await cookies();

  cookieStore.set("session", session, {
    httpOnly: true,
    secure: true,
    expires: expiresAt,
    sameSite: "lax",
    path: "/",
  });
}

export async function deleteSession() {
  const cookieStore = await cookies();
  cookieStore.delete("session");
  redirect("/login");
}

What's happening here: httpOnly: true keeps the cookie invisible to client-side JavaScript, which stops it from being stolen via an XSS attack. secure: true means it's only ever sent over HTTPS. sameSite: "lax" blocks the cookie from being attached to most cross-site requests, which is your main defense against CSRF here. None of this is JWT-specific — you'd want the exact same flags on a session-ID cookie too.

Verify the session with a Data Access Layer

Don't scatter decrypt() calls across every page. Centralize verification in one cached function — this is what Next.js's own docs call a Data Access Layer (DAL).

// lib/jwt/dal.ts
import "server-only";
import { cache } from "react";
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { decrypt } from "./session";

export const verifySession = cache(async () => {
  const cookieStore = await cookies();
  const token = cookieStore.get("session")?.value;
  const session = await decrypt(token);

  if (!session?.sub) {
    redirect("/login");
  }

  return { isAuth: true, userId: session.sub };
});

What's happening here: wrapping this in React's cache() means that no matter how many components on the same page call verifySession(), the actual decrypt-and-check logic only runs once per request — every subsequent call reuses the result. session.sub is the standard claim set by .setSubject() earlier, so this reads it back out under a friendlier userId name for the rest of your app. Call this at the top of any Server Component, Server Action, or Route Handler that needs to know who's logged in.

// app/dashboard/page.tsx
import { verifySession } from "@/lib/jwt/dal";

export default async function DashboardPage() {
  const { userId } = await verifySession();

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

Add an optimistic check in `proxy.ts`

In Next.js 16, middleware.ts was renamed to proxy.ts — same file convention, same idea. It's the first thing that runs before a request reaches a page, which makes it a good place for a fast, optimistic redirect. Full verification still happens in the DAL above — proxy.ts just avoids letting an obviously-unauthenticated request render a protected page at all.

// proxy.ts
import { NextRequest, NextResponse } from "next/server";

const protectedRoutes = ["/dashboard"];
const publicRoutes = ["/login", "/signup"];

export default function proxy(req: NextRequest) {
  const path = req.nextUrl.pathname;
  const isProtectedRoute = protectedRoutes.some((route) => path.startsWith(route));
  const isPublicRoute = publicRoutes.includes(path);

  // Optimistic check only — we just look for the cookie's presence.
  // We deliberately don't verify the signature here; that happens
  // in verifySession() inside the Data Access Layer.
  const cookie = req.cookies.get("session")?.value;

  if (isProtectedRoute && !cookie) {
    return NextResponse.redirect(new URL("/login", req.nextUrl));
  }

  if (isPublicRoute && cookie) {
    return NextResponse.redirect(new URL("/dashboard", req.nextUrl));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};

⚠️ Common Mistake: Treating proxy.ts as your only security check. It's a UX nicety that avoids a flash of protected content — it is not a substitute for re-verifying the session inside every Server Action and Route Handler that actually touches data. A request can always be sent directly, bypassing whatever page it "should" have come from.

Step 3: Build Database-Backed Sessions

Now the other approach — a real session table your server checks on each request.

Create the sessions table

-- Works for Postgres/Supabase; adjust types for your database
create table sessions (
  token_hash text primary key,
  user_id uuid not null references auth.users(id) on delete cascade,
  expires_at timestamptz not null,
  created_at timestamptz not null default now()
);

create index idx_sessions_user_id on sessions (user_id);

What's happening here: notice the primary key is token_hash, not token. We never store the raw session token in the database — only its hash. This mirrors how you'd never store a plaintext password: if your database ever leaked, an attacker with the hashes still couldn't reconstruct a working cookie.

⚠️ Cleanup: expiring a session only stops it from being accepted — the expires_at < now() check in verifyDbSession below handles that. It does not delete the row. Left alone, this table grows forever, one row per login, most of them long past their expiry date. Run a scheduled cleanup — a Vercel Cron job hitting a small Route Handler once a day is enough for most apps:
delete from sessions where expires_at < now();
This is purely a housekeeping/performance concern (an unbounded table gets slower to index and back up over time), not a security one — an expired row is already useless for authentication either way.

Create the session on login

// lib/db-session/create.ts
import "server-only";
import { randomBytes, createHash } from "crypto";
import { cookies } from "next/headers";
import { db } from "@/lib/db";

function hashToken(token: string) {
  return createHash("sha256").update(token).digest("hex");
}

export async function createDbSession(userId: string) {
  const token = randomBytes(32).toString("hex"); // goes to the browser
  const tokenHash = hashToken(token); // goes to the database
  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);

  await db.session.create({
    data: { tokenHash, userId, expiresAt },
  });

  const cookieStore = await cookies();
  cookieStore.set("session", token, {
    httpOnly: true,
    secure: true,
    sameSite: "lax",
    expires: expiresAt,
    path: "/",
  });
}

What's happening here: randomBytes(32) generates a token with enough entropy that guessing it is computationally infeasible — this is the piece doing the actual security work, not the hashing. We hash it with SHA-256 purely so a database leak doesn't hand out working session tokens; the browser still holds the real, unhashed token in its cookie.

Verify the session (with caching, so it doesn't hit the database on every render)

// lib/db-session/dal.ts
import "server-only";
import { cache } from "react";
import { cookies } from "next/headers";
import { createHash } from "crypto";
import { redirect } from "next/navigation";
import { db } from "@/lib/db";

function hashToken(token: string) {
  return createHash("sha256").update(token).digest("hex");
}

export const verifyDbSession = cache(async () => {
  const cookieStore = await cookies();
  const token = cookieStore.get("session")?.value;

  if (!token) redirect("/login");

  const tokenHash = hashToken(token);
  const session = await db.session.findUnique({
    where: { tokenHash },
    include: { user: true },
  });

  if (!session || session.expiresAt < new Date()) {
    redirect("/login");
  }

  return { isAuth: true, userId: session.userId, user: session.user };
});

What's happening here: just like the JWT version, cache() means one database lookup per request no matter how many components ask "who's logged in?" This is the piece that makes database sessions viable in practice — without it, a page with five components each checking auth would fire five identical queries.

Revoking a session — the whole point of this approach

// lib/db-session/delete.ts
"use server";

import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { createHash } from "crypto";
import { db } from "@/lib/db";

function hashToken(token: string) {
  return createHash("sha256").update(token).digest("hex");
}

export async function deleteDbSession() {
  const cookieStore = await cookies();
  const token = cookieStore.get("session")?.value;

  if (token) {
    await db.session.delete({ where: { tokenHash: hashToken(token) } }).catch(() => {});
  }

  cookieStore.delete("session");
  redirect("/login");
}

// Force-logout every session for a user — e.g. after a password reset
export async function revokeAllSessionsForUser(userId: string) {
  await db.session.deleteMany({ where: { userId } });
}

What's happening here: revokeAllSessionsForUser is the function you can't build with plain JWTs — one query, and every device that user is logged in on is instantly signed out, because the next request they make finds no matching row. This is the single biggest practical reason teams reach for database sessions over JWTs.

proxy.ts looks identical to the JWT version above — it's still just checking whether the session cookie exists, since that check never needed to know which auth strategy is behind it.

Session vs JWT: Side-by-Side

	Session (database)	JWT
Where the data lives	Server-side (database row)	Inside the token itself
Cookie contents	Random, meaningless ID	Signed, self-contained payload
Instant revocation	✅ Delete the row	❌ Not without extra machinery
Force-logout everywhere	✅ One query	❌ Requires a blocklist or short expiry + refresh
Per-request cost	One DB lookup (cacheable per request)	No DB call — just signature verification
Works well at scale / multi-server	Needs a shared database (usually already true)	Naturally stateless, nothing to share
Payload can go stale	No — always reads current data	Yes — data inside is frozen until re-issued
Implementation complexity	Slightly more (schema, hashing, cleanup)	Slightly less (no schema needed)
Best for	Apps where instant revocation matters (banking, admin tools, anything security-sensitive)	High-traffic, distributed systems where avoiding a DB hit per request matters

💡 Tip: "JWTs don't need a database" is true for verification, but most real apps still store something — a refresh-token table, a denylist, or at minimum a passwordChangedAt timestamp checked against the token's iat (issued-at) claim. The stateless promise of JWTs is a little softer in practice than it sounds in theory.

A Closer Look: What "Horizontal Scaling" Actually Means Here

"Naturally stateless" in the table above is doing a lot of work, so let's unpack it. Say your app runs on five server instances behind a load balancer — a request from the same user could land on a different instance every time.

With database sessions: whichever instance handles the request just needs to reach the same database everyone else does. In practice this is a non-issue for most Next.js apps, since you already have one shared database — every instance was already talking to it for everything else. The "scaling problem" people worry about here mostly doesn't exist unless you're deliberately running sessions in something instance-local, like in-memory storage (don't do that).
With JWTs: verification needs nothing but the signing secret, which every instance already has as an environment variable. No instance has to coordinate with any other instance, or with a database, to answer "is this token valid?" That's genuinely useful once you're running at the edge — Cloudflare Workers, Vercel Edge Functions — across multiple regions, where a round trip to a single-region database could add real, noticeable latency to every request.

So the honest version: for a typical app with one shared Postgres/Supabase database, this isn't really a deciding factor — you're already "horizontally scaled" for sessions for free. It starts to matter once you're running truly distributed, multi-region, or edge-first infrastructure where a database round trip per request is a real, measured cost, not a hypothetical one.

Sliding (Rolling) Sessions

So far, every example here uses a fixed expiry — log in, get 7 days, and after 7 days you're logged out no matter how active you were. A sliding session (also called a rolling session) instead extends the expiry every time the user does something, so an active user effectively never gets logged out, while an idle one still expires on schedule.

With database sessions, this is simple: on every successful verifyDbSession() call, update that row's expires_at to "now + 7 days" again.

  // Inside verifyDbSession, after confirming the session is valid
  await db.session.update({
    where: { tokenHash },
    data: { expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000) },
  });

One extra write per (cached) verification — cheap, and the source of truth (the row) is already being touched anyway.

💡 Tip: In production it's common to only extend the session once every few hours instead of on every request to avoid unnecessary writes.

With JWTs, this is more work: the exp claim is baked into the signature at issue time — you can't quietly extend it without re-signing a brand-new token and setting a brand-new cookie on the response. Doable inside a Route Handler or Server Action (create a fresh token with a new expiresAt, call cookies().set() again), but it means writing a cookie back on requests that otherwise wouldn't need one, which is easy to forget to wire up consistently across every route.

💡 Tip: If "stay logged in while active, expire after a week of silence" is a real requirement for your app, that alone is a reasonable tie-breaker toward database sessions — it's a one-line update there versus meaningfully more plumbing with JWTs.

Can You Get Revocation With JWTs?

Yes, with a tradeoff. Two common patterns:

Short expiry + refresh tokens. Issue an access token that expires in 10–15 minutes, plus a longer-lived refresh token stored in the database. To revoke, you delete the refresh token — the access token is still technically valid, but only for a few more minutes, which is an acceptable blast radius for most apps.
A denylist. Keep a small, fast-to-check store (Redis is the usual choice) of token IDs (jti claims) that have been explicitly revoked. Every verification also checks this list. This reintroduces a lookup on every request — at that point, you've mostly reinvented database sessions with extra steps.

Neither of these makes JWTs behave exactly like sessions — they just narrow the gap. If instant, guaranteed revocation is a hard requirement (think: a compromised admin account), database sessions remove the problem entirely instead of managing around it.

Which One Should You Actually Use?

Building a typical SaaS dashboard, internal tool, or content site? Database sessions. The DB hit is cheap with caching, and "log this user out right now" is a feature you'll eventually need, even if you don't think so today.
Building something with genuinely massive, distributed, stateless traffic (think: an API consumed by thousands of independent clients, or infrastructure where adding a database round trip to every request is a real cost)? JWTs earn their keep here.
Already using Auth.js or Clerk? You don't have to choose by hand — Auth.js exposes session: { strategy: "jwt" | "database" } directly, and Clerk manages this decision for you behind its own infrastructure.
Not sure yet? Default to database sessions. It's the safer, more debuggable choice, and the performance cost is rarely the bottleneck people assume it'll be — cache the lookup with cache() as shown above and it disappears from your profiler.

Frequently Asked Questions

Can I combine both approaches?

Yes — this is actually what "refresh tokens" are: a short-lived JWT for fast verification, backed by a database-stored refresh token for revocation. You get JWT-speed reads most of the time, with a real revocation point when you need one.

Is storing a JWT in a cookie the same as storing it in localStorage?

No, and the difference matters for security. An httpOnly cookie can't be read by client-side JavaScript, so it's protected from XSS attacks that steal tokens. localStorage is fully readable by any script running on your page — a single XSS vulnerability anywhere in your dependency tree can leak every token stored there. Always use httpOnly cookies for auth tokens in a Next.js app.

Does `proxy.ts` need to fully verify the session on every request?

No, and for JWT-based auth verifying in proxy.ts with jose is genuinely fine performance-wise since it needs no database call. The stronger rule is: never treat proxy.ts as your only check. Always re-verify inside the Server Action or Route Handler that actually reads or writes data — proxy.ts can be bypassed by hitting that endpoint directly.

Why hash the session token before storing it in the database?

The same reason you hash passwords — if your database is ever compromised (a leaked backup, a misconfigured access policy), the attacker gets a list of hashes they can't turn back into working session cookies. It costs you one sha256 call per request, which is effectively free.

Which one does Auth.js use by default?

Auth.js defaults to the "jwt" strategy unless you configure a database adapter, in which case it switches to "database" automatically. You can also set session: { strategy: "jwt" } explicitly even with an adapter configured, if you want JWTs for speed while still persisting user accounts.

Wrapping Up

Sessions and JWTs aren't competing standards — they're two different answers to "where does the source of truth for a logged-in user live?" Sessions keep it on your server, trading a database lookup for instant, total control over who stays logged in. JWTs keep it in the token itself, trading that control for verification that never has to leave the request.

For most Next.js apps, start with database sessions — the caching pattern above keeps the performance cost near zero, and you'll be glad revocation is a solved problem the first time you actually need it. Reach for JWTs specifically when you've measured that the database hit matters, not because a tutorial defaulted to it.

From here, a natural next step is wiring either pattern into a real login form with Zod validating the credentials before they ever reach your session logic, or layering role-based permissions on top of whichever session strategy you pick.

Continue Learning

Useful Resources

llms.txt Explained: What It Is, Who Uses It, and How to Add It to Next.js

Syed Muhammad Ali — Thu, 06 Aug 2026 04:08:25 +0000

You've probably seen a stray llms.txt link in someone's site footer, or noticed a new file sitting next to robots.txt and sitemap.xml on a docs site you visited. Maybe you've even been told "you need this or ChatGPT won't recommend your site." Before you spend an afternoon building one, it's worth asking the boring-but-important question nobody answers clearly: does anything actually read it?

The honest answer is more nuanced than the hype suggests — and also more nuanced than the dismissals. llms.txt is real, it has a real spec, and real companies use it. It's also not a magic AI-SEO switch, and it isn't officially supported by the major search engines or model providers the way robots.txt is.

By the end of this guide, you'll know exactly what llms.txt is, what it isn't, who actually fetches it today, and — if you decide it's worth it — how to add one to a Next.js 16 App Router site in a few minutes.

Why This Is Confusing

llms.txt gets compared to robots.txt constantly, which is exactly why people misunderstand it. robots.txt is a decades-old, genuinely standardized protocol that tells crawlers what they're allowed to request — if you haven't set yours up yet, our Google Search Console setup guide covers robots.ts and sitemap.ts from scratch. llms.txt looks similar — a plain text file at your site's root — but it does something completely different: it's a curated, human-and-LLM-readable summary of your site's most important content, meant to be read on demand when someone (or their AI assistant) is actively trying to understand your project.

It's also less than two years old, was proposed by one person, and isn't controlled by any standards body. That's not a knock on it — it just means "should I add this?" deserves a more grounded answer than "yes, everyone's doing it."

What Is llms.txt, Exactly?

llms.txt is a plain Markdown file you publish at https://yoursite.com/llms.txt. It was proposed on September 3, 2024 by Jeremy Howard of Answer.AI (the team behind fast.ai and FastHTML), as a way to solve a specific problem: large language models have limited context windows, and a full HTML page — full of navigation bars, ads, and JavaScript — is a wasteful, imprecise way to hand a model information about your site.

The idea is to give models a shortcut: one concise file, in a format they already parse well (Markdown), that says "here's what this site is, and here's where to find more detail if you need it."

Your Website

├── robots.txt
│      ↓
│   Search Crawlers

├── sitemap.xml
│      ↓
│   Index Discovery

└── llms.txt
       ↓
 AI Coding Agents

💡 Tip: llms.txt is a community-maintained specification, not a ratified web standard like HTTP or robots.txt's RFC. It's hosted and documented at llmstxt.org, with a public GitHub repo where people can propose changes.

The Required Format

The spec is intentionally strict about structure so both humans and simple parsers can read it reliably. A valid llms.txt file contains these sections, in this order:

An optional byte-order mark
An H1 with your project or site name — this is the only required section
A blockquote with a short summary containing the key facts someone needs to understand the rest of the file
Zero or more plain paragraphs or lists with more context (no headings allowed here)
Zero or more H2-delimited sections, each containing a Markdown list of links — these are your "file lists" pointing to more detailed pages

Here's the minimal shape:

# Project Name

> One or two sentences summarizing what this is and why it matters.

Optional extra context or notes go here — things like "this API isn't
compatible with X" or "written for developers who already know Y."

## Docs

- [Getting Started](https://example.com/docs/start.md): Setup and first steps
- [API Reference](https://example.com/docs/api.md): Full endpoint reference

## Optional

- [Changelog](https://example.com/changelog.md): Full version history

What's happening here: the H1 and blockquote are the only parts a model must be able to rely on — everything else is there to help it decide what to fetch next. That ## Optional section has special meaning in the spec: it's explicitly for secondary material that can be skipped if a model needs to save context space. Anything genuinely optional (a full changelog, an old migration guide) belongs there instead of in your main sections.

⚠️ Common Mistake: Treating llms.txt like robots.txt and trying to write "allow" or "disallow" rules into it. It has no access-control syntax at all — it's purely informational. If you want to control what AI crawlers can fetch, that's still robots.txt's job.

The Companion Idea: `.md` Versions of Your Pages

The original proposal also suggests something separate but related: serving a clean Markdown version of any page at the exact same URL, with .md appended. So example.com/docs/routing would also be reachable at example.com/docs/routing.md — the same content, minus the nav bar, ads, and JS chrome. This is optional, and most sites that adopt llms.txt skip it, but it's the other half of the same idea: give models plain text instead of forcing them to parse a full rendered page.

llms.txt vs robots.txt vs sitemap.xml

This is the comparison that actually matters, because each file solves a different problem:

File	Purpose	Who reads it	Format
`robots.txt`	Tells crawlers what they're allowed to request	Search engine and AI crawlers, generally respected	Simple directive syntax
`sitemap.xml`	Lists every indexable URL on your site, for discovery	Search engine crawlers	XML
`llms.txt`	A curated, concise summary of your most important content	Coding agents, some chatbots, on-demand — inconsistently	Markdown

The llms.txt spec itself is upfront about this distinction: it's designed to complement robots.txt and sitemap.xml, not replace either. A sitemap is exhaustive and built for indexing; llms.txt is deliberately small and curated, and it's meant to be pulled in at inference time — when someone's actually asking a question — rather than during a training run or a full crawl.

Does Anyone Actually Read It? (The Honest Answer)

This is the part most articles either oversell or dismiss entirely, so let's be precise.

What's confirmed:

Coding-focused AI tools — Cursor, GitHub Copilot, Windsurf, Claude Code, and similar IDE agents — do fetch llms.txt (and often llms-full.txt) when they're pointed at a documentation site or a library's docs, as part of pulling in relevant context before writing code.
Companies that ship developer tools — Anthropic, Stripe, Cloudflare, Vercel, Supabase, Mintlify, and others — publish one, largely for exactly that audience: developers and their AI coding assistants.

What's not confirmed:

Google has not stated that any of its crawlers use llms.txt to inform Search or AI Overviews. When asked directly why a site's llms.txt wasn't showing up in crawl logs, Google's John Mueller responded that no AI crawler has publicly confirmed that it extracts information via llms.txt.
A large-scale study covering roughly 300,000 domains (SE Ranking, late 2025) found adoption sitting around 10% of sites — modest growth after well over a year of industry conversation.
Search Engine Land reported that in a small sample of sites that added llms.txt, most saw no measurable change in AI referral traffic afterward.

So the realistic picture in 2026: llms.txt is a genuinely useful convention for developer-facing content consumed by coding agents and AI-assisted IDEs — but it is not a confirmed input to ChatGPT Search, Google AI Mode, or Perplexity's general web answers, and there's no solid evidence yet that adding one moves the needle on general AI citations or search rankings.

💡 Tip: Treat llms.txt the way you'd treat any unofficial-but-plausible SEO tactic: cheap to try, worth doing if it fits your site, but not something to obsess over or expect measurable ranking gains from.

Should Your Next.js Site Have One?

It depends entirely on what your site is:

You run a docs site, an SDK, an open-source library, or a developer tool (like DevStacked's tools and guides): yes, worth it. Your actual audience includes other developers whose coding assistants will genuinely benefit from a clean, curated summary — this is the use case the spec was built for.
You run a general blog, marketing site, or e-commerce store: lower priority. There's no confirmed benefit yet for general-purpose AI search visibility, and your time is probably better spent on the fundamentals — structured data, internal linking, and content depth — which are confirmed to matter for both traditional SEO and AI citations. See the complete technical SEO checklist for where to focus instead, and the JSON-LD Generator for structured data that's actually proven to affect rich results.
Either way: it costs almost nothing to add, doesn't conflict with anything else on your site, and gives you a clean, canonical "here's what this is" file you can point people (and their tools) to directly.

When You Probably Don't Need One

It's worth being just as direct about when to skip this. Adding llms.txt isn't harmful, but it isn't free either — it's one more file to keep accurate, and a stale or careless one is arguably worse than none at all. Skip it (for now) if:

You're pre-launch or pre-traffic. A curated summary file is only useful once there's something worth curating. Get your core pages, metadata, and content live first — see how to add metadata in Next.js 16 if that part isn't done yet.
Your site is small and already simple to crawl. A five-page marketing site doesn't need a curation layer — a model (or a human) can already understand it from the page content and your sitemap alone.
You don't have the bandwidth to keep it accurate. An llms.txt that still lists a deprecated API or a renamed pricing plan six months later actively misleads anything that reads it. If you can't commit to updating it alongside your content, it's better left out until you can.
You're chasing it purely for "AI SEO." As covered above, there's no confirmed ranking or citation benefit yet. If that's your only motivation, your time is better spent on things with a proven payoff — structured data, canonical URLs, and Core Web Vitals, all covered in the technical SEO checklist.

💡 Tip: If you're unsure, the safest default is: build it for genuinely developer-facing content (docs, tools, APIs) where coding agents are a real audience, and skip it everywhere else until the spec's adoption picture is clearer.

Step-by-Step: Adding llms.txt to a Next.js 16 App Router Site

This guide assumes Next.js 16 with the App Router, TypeScript in strict mode, and content that changes over time (like blog posts) — so we'll generate the file dynamically instead of hand-maintaining a static one.

Step 1: Decide Static or Dynamic

If your site's content is small and stable (a handful of pages that rarely change), a plain static file is simplest.

If you have a blog or a growing set of tools/docs pages — which is the more common case — generating the file from your existing data source keeps it accurate without manual upkeep every time you publish.

We'll build the dynamic version, since it's the one that actually needs explaining. If you want the static route, skip to the callout at the end of Step 3.

Step 2: Create a Route Handler for `/llms.txt`

Next.js Route Handlers can serve any content type at any path — including a plain text file — so this is the right tool for a file that needs to be generated per-request (or cached and revalidated). If Route Handlers are new to you, our full breakdown of Route Handlers in Next.js 16 covers the route.ts convention this step relies on.

// app/llms.txt/route.ts
import { getAllPosts } from "@/lib/posts";
import { TOOLS } from "@/lib/tools-data";
import { appURL } from "@/lib/utils";

export const dynamic = "force-static"; // safe to prerender — same content for every visitor

export function GET() {
  const posts = getAllPosts();

  const docsSection = posts
    .slice(0, 25) // keep the file focused — see the note on curation below
    .map((post) => `- [${post.title}](${appURL}/blog/${post.slug}): ${post.description}`)
    .join("\n");

  const toolsSection = TOOLS.map(
    (tool) => `- [${tool.name}](${appURL}${tool.href}): ${tool.tagline}`
  ).join("\n");

  const content = `# DevStacked

> DevStacked is a developer-focused site with practical Next.js, React, Supabase,
> and Stripe implementation guides, plus a set of free browser-based developer tools.

Guides are implementation-driven, covering real architecture decisions and
production code rather than surface-level tutorials.

## Tools

${toolsSection}

## Guides

${docsSection}

## Optional

- [Full sitemap](${appURL}/sitemap.xml): Every indexable page on the site
`;

  return new Response(content, {
    headers: {
      "Content-Type": "text/plain; charset=utf-8",
    },
  });
}

What's happening here:

The route lives at app/llms.txt/route.ts — Next.js folder names can include a dot, so this maps directly to the URL /llms.txt, no rewrites needed.
export const dynamic = "force-static" tells Next.js this route's output doesn't depend on the incoming request, so it can be generated once at build time instead of on every visit — the same optimization your sitemap.ts and robots.ts files already get.
The response sets Content-Type: text/plain; charset=utf-8 instead of the default JSON or HTML content type, since llms.txt is meant to be read as plain Markdown text, not rendered.
Only the 25 most recent posts are included in the main section — see the note below on why bigger isn't better here.

⚠️ Common Mistake: Dumping your entire sitemap into llms.txt. The spec exists specifically because full-page dumps are what sitemap.xml is already for — llms.txt is supposed to be a curated shortlist. If every single page is listed, you've just built a worse, non-standard sitemap that a model has no more reason to trust than the real one.

Step 3: Verify the Output

Run your dev server and visit the route directly:

npm run dev

Then open http://localhost:3000/llms.txt in your browser. You should see plain Markdown text (not rendered HTML) — if your browser tries to download it or shows raw HTML instead, double-check the Content-Type header in Step 2.

💡 Static-site alternative: If your content doesn't change often, skip the Route Handler entirely and just drop a hand-written llms.txt file into /public/llms.txt. Anything in public/ is served as-is at the site root, so public/llms.txt becomes yoursite.com/llms.txt automatically — no route code needed. This is the simpler option for a personal site or a small marketing site with a handful of pages.

Step 4: Link to It From robots.txt (Optional, but Tidy)

Since the spec says llms.txt is meant to coexist with robots.txt, it's a reasonable place to reference it — the same way you already point to your sitemap:

// app/robots.ts
import { appURL } from "@/lib/utils";
import { MetadataRoute } from "next";

export default function robots(): MetadataRoute.Robots {
  return {
    rules: {
      userAgent: "*",
      allow: "/",
    },
    sitemap: `${appURL}/sitemap.xml`,
  };
}

There's no official field for referencing llms.txt inside robots.txt — this step is just a discoverability nicety, not part of the spec. A simple comment-style mention or a link from your footer/README works just as well.

Step 5: Keep It Curated, Not Comprehensive

The single biggest quality mistake is treating llms.txt like a dumping ground. A few concrete guidelines from the spec authors, worth following:

Use plain, unambiguous language — avoid jargon you haven't already defined
Give every linked resource a short, informative description, not just a bare link
Put genuinely secondary material (old changelogs, deprecated docs) under the ## Optional heading so it's easy for a model to skip
If your file starts feeling long, that's a sign to trim it, not add a summary section on top of it

Frequently Asked Questions

Does llms.txt help my Google rankings?

No confirmed evidence of that yet. Google's own John Mueller has said no AI crawler has confirmed using llms.txt for content extraction, and it isn't part of Google's documented Search ranking systems. Treat it as separate from your regular SEO work — Google Search Console and a solid technical SEO checklist are still where the confirmed ranking signals live.

Is llms.txt an official web standard?

No — it's a community-maintained convention proposed by Jeremy Howard of Answer.AI in September 2024, documented at llmstxt.org. There's ongoing community discussion about formalizing it further, but as of now there's no ratified standards-body specification the way there is for robots.txt.

Will ChatGPT or Perplexity actually read my llms.txt?

Not reliably, based on current evidence. The clearest, best-documented use case today is coding tools and IDE agents (Cursor, GitHub Copilot, Claude Code, and similar) fetching a project's llms.txt when a developer is working with that library. General-purpose chat search products haven't confirmed using it the same way.

Should I generate llms.txt dynamically or just write it by hand?

If your content is small and stable, hand-writing a static file in public/llms.txt is simpler and easier to review. If you have a blog or a growing tools page, generating it from the same data source your site already uses (like getAllPosts()) keeps it accurate without extra manual work every time you publish.

Can llms.txt block AI crawlers from my content?

No — it has no access-control syntax at all. It's purely descriptive. If you want to allow or block specific AI crawlers, that's still handled through robots.txt, using each crawler's documented user-agent string.

Wrapping Up

llms.txt is a real, well-specified convention — not an official standard, but not vaporware either. It has a clear, honest use case today: helping AI coding tools and IDE agents quickly understand a developer-facing site without wading through rendered HTML. For a project like a Next.js tools-and-guides site, it's a cheap, low-risk addition. What it isn't, at least as of now, is a proven lever for general AI search visibility or Google rankings — so add it because it genuinely helps your developer audience, not because someone promised it'll get you cited by ChatGPT.

If you're already generating sitemap.ts and robots.ts from your post data, adding app/llms.txt/route.ts following the same pattern takes about ten minutes — and now you know exactly what it will, and won't, actually do.

Continue Learning

Free SEO Tools

Meta Tag Generator for Next.js & HTML — generate SEO meta tags, Open Graph tags, canonical URLs, and JSON-LD in one pass.
JSON-LD Generator for Next.js & HTML — generate structured data checked live against Google's actual Rich Results requirements, not just schema.org validity.

Feature Flags in SaaS: A Beginner's Guide with Next.js 16 (2026)

Syed Muhammad Ali — Tue, 04 Aug 2026 04:40:31 +0000

You just shipped a new billing page. It works perfectly in your local environment, QA gives it a thumbs up, and you deploy on a Friday afternoon (bold choice). Twenty minutes later, support tickets start rolling in — the new checkout flow is broken for a chunk of your users, and the only fix is a full redeploy, which means more downtime while you scramble.

Here's the thing: that entire scenario is avoidable. Not by testing harder, but by changing how you ship. If that billing page had been behind a feature flag, you could've turned it off instantly — no redeploy, no rollback, no 2am panic. Just a toggle switch.

By the end of this guide, you'll understand exactly what feature flags are, why almost every real SaaS product uses them, and you'll have a working feature flag system built into a Next.js 16 app — from a simple database-backed version you can build yourself, to Vercel's official Flags SDK for a more polished setup.

Why This Is Tricky

Feature flags sound simple — "just an if statement," right? And technically, that's true. But most beginners either overuse them (turning every branch of code into a flag, creating a tangled mess) or underuse them (skipping flags entirely and relying only on git push to control what users see).

The real skill isn't writing an if statement — it's answering three questions correctly:

Where should the flag be checked? Client, server, or both?
Where should the flag's value live? Hardcoded, a database, or a third-party service?
What happens when the flag is wrong or missing? Does your app break, or fail safely?

We'll answer all three as we build this out.

What Is a Feature Flag, Exactly?

A feature flag (also called a feature toggle) is a switch in your code that controls whether a piece of functionality is active — without needing to change or redeploy your code to flip it.

💡 Think of it like: a light switch wired into your wall during construction, instead of soldering a lamp directly to the power line. The wiring (your code) ships once. Whether the light is on or off is a decision you can change any time, without touching the wall again.

In practice, a feature flag is just a boolean (or sometimes a string/number) that your code checks before rendering something or running some logic:

if (isNewCheckoutEnabled) {
  return <NewCheckout />;
}

return <OldCheckout />;

The interesting part isn't that if statement — it's where isNewCheckoutEnabled comes from and how you control it. That's what the rest of this guide covers.

Why SaaS Products Rely on Feature Flags

A handful of concrete reasons feature flags matter, especially for SaaS:

Ship without releasing. You can merge and deploy unfinished code to production behind a flag that's off. This is called "trunk-based development" — your main branch always reflects what's deployed, but not everything deployed is visible yet.
Instant kill switch. If something breaks, flip the flag off. No git revert, no redeploy, no waiting for a build to finish while your app is broken.
Gradual rollouts. Release a risky feature to 5% of users first, watch for errors, then dial it up to 25%, 50%, 100% — instead of an all-or-nothing launch.
Paid plan gating. Show a feature only to customers on your Pro or Enterprise plan, without maintaining separate codebases per plan.
A/B testing. Show two variants of a feature to different user segments and measure which one performs better.
Beta programs. Let specific users (or your own team) try a feature early, without exposing it to everyone.

💡 Tip: These use cases usually map to four flag types: release flags (hide unfinished work), ops flags (kill switches), permission flags (plan-based access), and experiment flags (A/B tests). Naming your flags after their type helps keep a growing flag list organized — more on this in the best-practices section.

Prerequisites

This guide uses:

Next.js 16 with the App Router
TypeScript in strict mode
Supabase as the database (the same pattern works with any Postgres/SQL database — just swap the client)
Tailwind CSS for the tiny UI examples

We'll build two versions of the same thing:

A do-it-yourself, database-backed flag system — no extra service, full control, great for learning how flags actually work under the hood.
The Vercel Flags SDK — an official, open-source toolkit purpose-built for Next.js that adds typed flags, a local override toolbar, and a clean pattern for swapping providers later.

You don't need both — pick whichever fits your project, or read both to understand the tradeoffs.

  User Request
      │
      ▼
Server Component
      │
      ▼
getFeatureFlag()
      │
      ▼
Next.js Cache
      │
      ├── Cache Hit ─────► true / false
      │
      ▼
  Supabase
      │
      ▼
 true / false
      │
      ▼
  Render UI

Part 1: Building Your Own Feature Flag System

This is the version to reach for if you want zero extra dependencies and full control over where flag data lives — a great fit if you're already using Supabase for your app's database.

Step 1: Create the Feature Flags Table

Every flag needs a key (a unique name), whether it's enabled, and optionally a rollout percentage for gradual releases.

-- Run this in the Supabase SQL editor
create table public.feature_flags (
  key text primary key,
  enabled boolean not null default false,
  rollout_percentage int not null default 100
  check (rollout_percentage between 0 and 100),
  description text,
  updated_at timestamptz not null default now()
);

-- Keep RLS on with no policies — only a service-role client can read this,
-- not even your normal server-side (cookie-based) Supabase client, and never the anon key.
alter table public.feature_flags enable row level security;

What's happening here: key is a plain text primary key like "new-checkout" — your code will reference flags by this string. enabled is the master on/off switch. rollout_percentage lets you release to a slice of users instead of everyone at once (100 means "everyone who has the flag enabled sees it," 25 means "only about a quarter of them do"). Enabling Row Level Security with no policies means this table isn't readable through the public API at all — only your server-side Supabase client (which uses full database access) can read it, which is exactly what you want for something that controls app behavior.

⚠️ Common Mistake: Leaving this table world-readable through the anon key. Even though flag values aren't usually "secret" in the sensitive-data sense, exposing your entire flag list (including unreleased feature names) to anyone poking at your API is an easy, avoidable leak.

Add a couple of test rows:

insert into public.feature_flags (key, enabled, rollout_percentage, description)
values
  ('new-checkout', true, 100, 'Redesigned checkout flow'),
  ('ai-summary', true, 20, 'AI-generated summary panel (early rollout)');

Step 2: Write a Deterministic Rollout Function

If rollout_percentage is 20, you want the same 20% of users to see the feature every time they visit — not a random 20% on every page load. That requires a deterministic check: given the same user and the same flag, always return the same answer.

// lib/flags/rollout.ts
import { createHash } from "crypto";

/**
 * Deterministically decides whether a given user falls inside a flag's
 * rollout percentage. The same userId + flagKey combination always
 * produces the same result, so a user doesn't flicker between the old
 * and new experience on every request.
 */
export function isInRollout(
  userId: string,
  flagKey: string,
  percentage: number
): boolean {
  if (percentage >= 100) return true;
  if (percentage <= 0) return false;

  const hash = createHash("sha256")
    .update(`${flagKey}:${userId}`)
    .digest("hex");

  // Take the first 8 hex characters, turn them into a number,
  // and reduce it to a bucket between 0 and 99.
  const bucket = parseInt(hash.slice(0, 8), 16) % 100;

  return bucket < percentage;
}

What's happening here: createHash("sha256") hashes the combination of the flag key and the user's ID. Because hashing is deterministic (the same input always produces the same output), the same user always lands in the same "bucket" (a number from 0–99) for a given flag. If that bucket number is less than the rollout percentage, they see the feature. Since we mix in the flag key too, the same user can be in the "in" bucket for one flag and the "out" bucket for a completely different flag — buckets aren't shared across flags.

Step 3: Create a Server-Only Function to Read a Flag

First create a service-role Supabase client

The feature_flags table has RLS enabled with no policies, so it can't be read by any client except one authenticated with your service role key — not even your normal server-side (cookie-based) Supabase client can see it. That's actually a good fit here, since flags are app-level configuration, not user data, and it also happens to be the client we need for caching: it has no cookies or per-request session attached, which Next.js requires for anything wrapped in "use cache".

// lib/supabase/service-client.ts
import { createClient } from "@supabase/supabase-js";

// Service-role client — bypasses RLS, no cookies/session attached.
// Only ever use this for trusted, server-only reads like feature flags.
// Never import it into a Client Component, and never prefix the key with NEXT_PUBLIC_.
export const supabaseAdmin = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

⚠️ Common Mistake: Leaking the service role key to the browser. It must stay a plain (non-NEXT_PUBLIC_) environment variable, set only in your server environment — this key bypasses every RLS policy in your database, so treat it with the same care as a database password.

// lib/flags/get-flag.ts
import { supabaseAdmin } from "@/lib/supabase/service-client";
import { isInRollout } from "./rollout";

/**
 * Reads a feature flag's value for a given user.
 * Server-only — never call this from a Client Component.
 */
export async function getFeatureFlag(
  key: string,
  userId?: string
): Promise<boolean> {
  const { data, error } = await supabaseAdmin
    .from("feature_flags")
    .select("enabled, rollout_percentage")
    .eq("key", key)
    .maybeSingle();

  // Fail safe: an unknown or errored flag defaults to "off",
  // not "on" — a missing flag should never accidentally expose
  // an unfinished feature to everyone.
  if (error || !data || !data.enabled) {
    return false;
  }

  // No user context (e.g. a public page) — just use the master switch.
  if (!userId) {
    return data.rollout_percentage >= 100;
  }

  return isInRollout(userId, key, data.rollout_percentage);
}

What's happening here: this function is the single place that knows how to read a flag — every page, Server Action, or Route Handler in your app calls through here instead of querying Supabase directly. Notice the fail-safe default: if the flag doesn't exist, or the database call errors out, we return false. That's a deliberate choice — a flag failing "closed" (off) is almost always safer than failing "open" (on), since an unexpected true could expose an unfinished feature to every user.

Caching Feature Flag Reads with `next/cache`

Right now, getFeatureFlag() hits Supabase on every single call. If a flag is checked on a high-traffic page — or several times per request, once per feature — that's a lot of avoidable database round trips for data that barely changes. A hand-rolled in-memory cache can fix that, but it comes with real downsides in production: it only lives inside one serverless function instance (so different instances can disagree), and it disappears completely on every cold start or redeploy. Next.js already ships a caching layer built for exactly this — reach for that instead of reinventing it.

The good news: the shared part of a flag (its enabled state and rollout_percentage) is identical for every user. Only the final true/false decision is per-user, and that part is just cheap in-memory hashing. So you only need to cache the database row, not the per-user result.

Caching the flag row

// lib/flags/get-flag.ts
import { cacheLife, cacheTag } from "next/cache";
import { supabaseAdmin } from "@/lib/supabase/service-client";
import { isInRollout } from "./rollout";

type FlagRow = { enabled: boolean; rollout_percentage: number };

async function fetchFlagRow(key: string): Promise<FlagRow | null> {
  "use cache";
  cacheLife("minutes"); // safety-net expiry if nothing ever invalidates it
  cacheTag(`feature-flag:${key}`); // lets us invalidate just this one flag

  const { data, error } = await supabaseAdmin
    .from("feature_flags")
    .select("enabled, rollout_percentage")
    .eq("key", key)
    .maybeSingle();

  return error ? null : data;
}

export async function getFeatureFlag(
  key: string,
  userId?: string
): Promise<boolean> {
  const row = await fetchFlagRow(key);

  if (!row || !row.enabled) return false;
  if (!userId) return row.rollout_percentage >= 100;

  return isInRollout(userId, key, row.rollout_percentage);
}

What's happening here: "use cache" at the top of fetchFlagRow marks that function as a cache boundary — Next.js automatically derives the cache key from the function's arguments (key), so each flag gets its own independent cache entry with no manual key-building required. cacheLife("minutes") applies one of Next.js's built-in expiry profiles as a fallback expiry (a handful of minutes), in case nothing ever explicitly invalidates it. cacheTag(\feature-flag:${key}) is the important part for production use — it lets you invalidate exactly one flag on demand instead of waiting for the fallback expiry or flushing every cached flag at once.

💡 Tip: "use cache" requires Cache Components to be enabled in next.config.ts:

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

If your project isn't on Cache Components yet, use the older unstable_cache API instead — same tagging idea, just a wrapper function instead of a directive:

import { unstable_cache } from "next/cache";

const fetchFlagRow = (key: string) =>
  unstable_cache(
    async () => {
      const { data, error } = await supabaseAdmin
        .from("feature_flags")
        .select("enabled, rollout_percentage")
        .eq("key", key)
        .maybeSingle();
      return error ? null : data;
    },
    ["feature-flag", key],
    { tags: [`feature-flag:${key}`], revalidate: 60 }
  )();

Invalidating a flag the moment it changes

Caching only pays off if flipping a flag actually takes effect quickly. Instead of waiting out cacheLife's fallback window, invalidate the specific tag the moment an admin updates the row:

// actions/toggle-feature-flag.ts
"use server";

import { revalidateTag } from "next/cache";
import { supabaseAdmin } from "@/lib/supabase/service-client";

export async function toggleFeatureFlag(key: string, enabled: boolean) {
  const { error } = await supabaseAdmin
    .from("feature_flags")
    .update({ enabled, updated_at: new Date().toISOString() })
    .eq("key", key);

  if (error) {
    return { error: error.message };
  }

  // Instantly invalidates only this flag's cached row — every
  // subsequent getFeatureFlag() call re-fetches fresh data.
  revalidateTag(`feature-flag:${key}`);

  return { success: true };
}

What's happening here: revalidateTag(\feature-flag:${key}) tells Next.js's cache "anything tagged with this string is now stale" — the very next call to fetchFlagRow(key) skips the cache and re-fetches from Supabase, then caches the fresh result under the same tag. This is what makes a cached flag system still behave like an instant kill switch: the cache saves you database round trips on the read path, while revalidateTag guarantees a write is reflected immediately, not after some fixed delay.

⚠️ Common Mistake: Updating the feature_flags table directly from the Supabase dashboard and expecting the change to show up right away. The cache has no way to know the row changed unless something calls revalidateTag() — always flip flags through a path (like the Server Action above) that revalidates the tag, or expect to wait out the cacheLife window.

Step 4: Use the Flag in a Server Component

// app/dashboard/page.tsx
import { getFeatureFlag } from "@/lib/flags/get-flag";
import { getCurrentUser } from "@/lib/auth"; // whatever your auth setup returns
import { NewDashboard } from "@/components/dashboard/new-dashboard";
import { OldDashboard } from "@/components/dashboard/old-dashboard";

export default async function DashboardPage() {
  const user = await getCurrentUser();
  const showNewDashboard = await getFeatureFlag("new-dashboard", user?.id);

  return showNewDashboard ? <NewDashboard /> : <OldDashboard />;
}

What's happening here: because DashboardPage is an async Server Component, we can await getFeatureFlag(...) directly during render — no loading spinner, no client-side fetch, no flicker between the two versions. The flag is resolved once, on the server, before any HTML reaches the browser.

Step 5: Use the Same Flag in a Server Action

Flags aren't just for showing/hiding UI — sometimes you want to gate a whole action, like a new AI feature that costs you money per call.

// actions/generate-summary.ts
"use server";

import { getFeatureFlag } from "@/lib/flags/get-flag";
import { getCurrentUser } from "@/lib/auth";

export async function generateSummary(text: string) {
  const user = await getCurrentUser();

  if (!user) {
    return { error: "You must be signed in." };
  }

  const enabled = await getFeatureFlag("ai-summary", user.id);

  if (!enabled) {
    return { error: "This feature isn't available yet." };
  }

  // ... call your AI provider here
  return { summary: "..." };
}

What's happening here: re-checking the flag inside the Server Action matters even though the button that triggers it is already hidden by the flag in the UI. A hidden button doesn't stop someone from calling the Server Action directly — the server-side check is your real gate, the UI check is just for user experience.

⚠️ Common Mistake: Only checking a flag in the UI (hiding a button) and assuming that's enough. Server Actions are callable endpoints under the hood — always re-verify anything sensitive on the server, the same way you would with authentication or authorization checks.

Part 2: Using the Vercel Flags SDK

The do-it-yourself version above works fine, but as your flag list grows you'll want a few things it doesn't give you: a typed, centralized list of every flag in your app, a way to preview flag values locally without touching the database, and a consistent pattern if you ever want to swap in a dedicated flag provider later.

That's exactly what the Flags SDK (built by the Vercel/Next.js team) solves. It's free, open source, framework-native for Next.js, and — importantly — it works with any data source, including the Supabase table you just built. You're not locked into a specific vendor.

Step 1: Install the SDK

npm install flags

Step 2: Generate a Flags Secret

The SDK uses a secret key to encrypt flag values when they're referenced by its local override tooling. Generate one with Node:

node -e "console.log(crypto.randomBytes(32).toString('base64url'))"

Copy the output into your environment variables:

# .env.local
FLAGS_SECRET=your-generated-secret-here

💡 Tip: Use a different FLAGS_SECRET value for each environment (development, preview, production). If you're deploying on Vercel, set each one with vercel env add FLAGS_SECRET production --sensitive.

Step 3: Define Your Flags in One File

This is the part that makes the SDK worth using — every flag in your app is declared once, as a typed function, in a single file.

// flags.ts
import { flag } from "flags/next";
import { getFeatureFlag } from "@/lib/flags/get-flag";
import { getCurrentUser } from "@/lib/auth";

export const newDashboardFlag = flag<boolean>({
  key: "new-dashboard",
  description: "Show the redesigned dashboard layout",
  decide: async () => {
    const user = await getCurrentUser();
    return getFeatureFlag("new-dashboard", user?.id);
  },
});

export const aiSummaryFlag = flag<boolean>({
  key: "ai-summary",
  description: "AI-generated summary panel (early rollout)",
  decide: async () => {
    const user = await getCurrentUser();
    return getFeatureFlag("ai-summary", user?.id);
  },
});

What's happening here: flag() wraps each feature into its own reusable, typed function. Notice the decide function is just calling the exact same getFeatureFlag() helper you already built in Part 1 — the SDK doesn't replace your data source, it sits on top of it. This means you get the SDK's developer experience (typed flags, the local toolbar, easy provider swaps later) while still owning your data in Supabase.

💡 Tip: Turning every flag into its own exported function means your editor's "Find All References" feature works — you can instantly see every place a flag is used, and confidently delete it once it's no longer needed.

Step 4: Use a Flag in a Page

// app/dashboard/page.tsx
import { newDashboardFlag } from "@/flags";
import { NewDashboard } from "@/components/dashboard/new-dashboard";
import { OldDashboard } from "@/components/dashboard/old-dashboard";

export default async function DashboardPage() {
  const showNewDashboard = await newDashboardFlag();

  return showNewDashboard ? <NewDashboard /> : <OldDashboard />;
}

What's happening here: calling newDashboardFlag() runs the decide function you defined in flags.ts and returns the resolved boolean. Notice there are no arguments at the call site — the flag function already knows how to figure out the current user internally. This is intentional: it keeps every call site simple and makes flags easy to reason about, since the logic for how a flag is decided lives in exactly one place.

⚠️ Common Mistake: Trying to call a flag function from a Client Component. Flags SDK flags are server-only by design — this avoids client-side loading spinners and keeps the decision logic (which might touch a database or user session) off the browser entirely. If a Client Component needs the value, resolve it in the parent Server Component and pass it down as a prop.

Step 5: Conditionally Render a Client Component

// app/dashboard/page.tsx
import { aiSummaryFlag } from "@/flags";
import { SummaryPanel } from "@/components/dashboard/summary-panel";

export default async function DashboardPage() {
  const showAiSummary = await aiSummaryFlag();

  return (
    <div className="space-y-6">
      <h1 className="text-2xl font-semibold">Dashboard</h1>
      {showAiSummary && <SummaryPanel />}
    </div>
  );
}

// components/dashboard/summary-panel.tsx
"use client";

export function SummaryPanel() {
  // Interactive logic here — the flag decision already
  // happened on the server before this component ever rendered.
  return (
    <div className="rounded-xl border p-4">
      <p className="text-sm text-muted-foreground">AI summary coming soon…</p>
    </div>
  );
}

What's happening here: the Server Component resolves the flag once and only renders <SummaryPanel /> at all if the flag is on. The Client Component itself never needs to know a flag exists — it just renders when it's asked to. This keeps the flag-checking logic entirely on the server, which is both simpler and safer than shipping the flag's raw value to the browser.

Best Practices for Feature Flags

A handful of habits that keep a growing flag system from turning into a mess:

Name flags consistently. Use a predictable pattern like kebab-case with a type hint, e.g. release-new-checkout, experiment-pricing-copy, ops-disable-emails, permission-ai-summary. It makes a flag's purpose obvious at a glance.
Default to "off" everywhere. As shown in getFeatureFlag(), an unknown, missing, or errored flag should resolve to false. Fail closed, not open.
Delete flags once they've served their purpose. A release flag that's been at 100% for a month and never gets turned off isn't a flag anymore — it's just a permanent if statement adding complexity. Remove it and the dead code branch behind it.
Never gate real security on a flag alone. A feature flag controls visibility, not authorization. Someone technically could still reach a hidden feature by calling the underlying Server Action or API route directly — always pair a flag with a real permission check for anything sensitive (see Step 5 in Part 1).
Test both states. Before shipping, manually verify your app behaves correctly with the flag both on and off — it's easy to only test the "on" path and forget the fallback still needs to work.
Keep the rollout logic deterministic. As covered in Part 1, a user should see a consistent experience across requests, not a coin flip on every page load.

     Create
       ↓
    Develop
       ↓
Internal Testing
       ↓
       5%
       ↓
      25%
       ↓
      50%
       ↓
     100%
       ↓
    Delete

Frequently Asked Questions

Do I need a third-party service like LaunchDarkly to use feature flags?

No. A single database table, like the feature_flags table built in Part 1, is enough for most SaaS apps — especially early on. Third-party feature flag platforms add real value once you need advanced targeting rules, detailed analytics per flag, or a non-technical team managing flags through a dashboard, but they're not a requirement to get started.

What's the difference between a feature flag and an environment variable?

An environment variable is set at build or deploy time and requires a redeploy to change. A feature flag is checked at runtime and can be flipped instantly without touching your deployment — that's the whole point. Use environment variables for configuration (API keys, database URLs) and feature flags for behavior that needs to change without a redeploy.

Can I use feature flags for A/B testing?

Yes — this is one of the most common uses. Instead of a simple on/off boolean, an experiment flag typically returns one of several variants (e.g. "control" or "variant-b"), and you track which variant a user saw alongside your analytics events to measure the difference in behavior.

Do feature flags have to be true/false?

No — boolean is just the simplest case. Many production flags are multivariate: instead of resolving to true/false, they resolve to one of several named values, like "control", "variant-a", or "variant-b". This is what powers most pricing, copy, and layout experiments, where you're comparing more than two options at once. The pattern in this guide extends naturally — swap the enabled boolean column for a value column (text or jsonb), and type your Flags SDK flag as flag<string>({...}) instead of flag<boolean>({...}) so decide() returns the variant name instead of a boolean. Everything else — the deterministic bucketing, the caching, the server-only checks — works exactly the same way.

Are feature flags secure enough to gate paid features?

A flag can decide whether to show a paid feature, but it should never be the only check. Always verify the user's actual subscription/permission status on the server (inside the Server Action or API route that does the real work) — the flag is a UX layer on top of that, not a replacement for it.

How many feature flags is too many?

There's no hard number, but if you regularly can't remember what a flag does or find yourself afraid to delete one, that's a sign your flag list needs cleanup. A good habit is reviewing flags monthly and removing any release flag that's been fully rolled out and stable for a few weeks.

Does checking a flag slow down my page?

If you're checking the same flags on every request, the Next.js caching approach from the Caching Feature Flag Reads with next/cache section removes most of that cost while still allowing immediate invalidation with revalidateTag().

Wrapping Up

Feature flags turn deployment and release into two separate decisions — you can ship code to production without exposing it, roll features out gradually, and flip a broken feature off in seconds instead of scrambling through a redeploy. You've now got two working approaches: a simple, fully self-owned system backed by a Supabase table, and the Vercel Flags SDK layered on top of it for a more polished, typed developer experience.

Start small — pick one risky upcoming feature, put it behind a flag using the Part 1 pattern, and get comfortable with the workflow before rolling flags out across your whole app.

Continue Learning

Error Handling in Next.js 16: The Complete 2026 Guide

Syed Muhammad Ali — Mon, 03 Aug 2026 04:17:15 +0000

Ever shipped a Next.js app, then watched one bad API response take down the entire page — header, sidebar, footer, everything — just because one component threw an error? You're not alone. It's one of the most common "gotchas" for developers moving from pages/ to the App Router.

The good news: Next.js 16 gives you a proper, file-based system for handling errors at exactly the level you want — a single component, a whole route segment, or the entire app. No more wrapping every component in a manual try/catch and hoping for the best.

By the end of this guide, you'll know exactly which error file to use and when, how to handle errors in Server Actions and Route Handlers the right way, and how to avoid the mistakes that leave users staring at a blank white screen in production.

Situation	Use
Rendering error	error.tsx
Root layout crash	global-error.tsx
Missing resource	not-found.tsx
Unknown URL	global-not-found.tsx
Form submission	Server Action
API endpoint	Route Handler

Why This Is Tricky

In the old Pages Router, error handling meant a single _error.js file for your whole app — crude, but simple. The App Router splits rendering into Server Components, Client Components, Server Actions, and Route Handlers, and each one fails differently:

A Server Component can throw during data fetching
A Client Component can throw during rendering
A Server Action can fail during a form submission
A Route Handler (API route) can fail while processing a request

Each of these needs its own handling strategy — that's why Next.js gives you multiple tools instead of one. Let's go through them one by one.

💡 Prerequisites: This guide uses Next.js 16 (App Router), TypeScript in strict mode, React Compiler (enabled by default, so no manual useMemo/useCallback needed), and Tailwind CSS for styling. Node.js 20.9+ is required.

Step 1: Catch Rendering Errors with `error.tsx`

An error boundary is a component that catches errors happening below it in the tree and shows a fallback UI instead of crashing everything. Next.js builds this in automatically — you just add a file called error.tsx to any route segment (a folder inside app/).

// app/dashboard/error.tsx
"use client"; // error.tsx must always be a Client Component

import { useEffect } from "react";

interface ErrorPageProps {
  error: Error & { digest?: string };
  reset: () => void;
}

const DashboardError = ({ error, reset }: ErrorPageProps) => {
  useEffect(() => {
    // Send the error to your monitoring tool (Sentry, Datadog, etc.)
    console.error("Dashboard error:", error);
  }, [error]);

  return (
    <div className="flex flex-col items-center justify-center gap-4 p-10 text-center">
      <h2 className="text-xl font-bold">Something went wrong</h2>
      <p className="text-sm text-gray-500">
        We couldn&apos;t load your dashboard. This has been logged.
      </p>
      <button
        onClick={() => reset()}
        className="rounded-md bg-black px-4 py-2 text-white"
      >
        Try again
      </button>
    </div>
  );
};

export default DashboardError;

What just happened:

Next.js automatically wraps the route segment in a React error boundary and renders this file when a rendering error occurs
error is the thrown error object. In production, Next.js strips sensitive details and only sends a generic message plus a digest — a hash you can match against your server logs
reset() tells React to try rendering the segment again — useful for transient errors like a flaky network request
The useEffect is where you report the error to a monitoring service, since error.tsx won't automatically show up in your logging tool

⚠️ Common Mistake: Putting error.tsx at the root of app/ and expecting it to catch everything. It can't — see Step 2.

Scoping Errors to the Right Level

Place error.tsx inside the specific folder you want to protect. A crash in one section won't take down the rest of the app.
Think of error.tsx like nested try/catch blocks. Next.js always looks for the nearest boundary first, then continues bubbling upward until it finds one.

app/
  dashboard/
    layout.tsx        ← sidebar stays visible even if a child crashes
    page.tsx
    error.tsx          ← catches errors from all dashboard routes
    analytics/
      page.tsx
      error.tsx        ← catches errors only in /dashboard/analytics
    settings/
      page.tsx         ← no error.tsx here, so errors bubble up to dashboard/error.tsx

If /dashboard/analytics crashes, only that section shows the fallback — the sidebar in layout.tsx keeps working. If /dashboard/settings crashes, since it has no error.tsx of its own, the error bubbles up to dashboard/error.tsx.

Step 2: Handle Root Layout Errors with `global-error.tsx`

There's one blind spot error.tsx can't cover: errors thrown inside the root layout itself (app/layout.tsx). Since the root layout wraps your entire app — including every error.tsx boundary — it needs its own separate mechanism.

// app/global-error.tsx
"use client";

interface GlobalErrorProps {
  error: Error & { digest?: string };
  reset: () => void;
}

const GlobalError = ({ error, reset }: GlobalErrorProps) => {
  return (
    <html>
      <body>
        <div style={{ textAlign: "center", padding: "3rem" }}>
          <h2>Something went seriously wrong</h2>
          <p>We&apos;ve been notified and are looking into it.</p>
          <button onClick={() => reset()}>Try again</button>
        </div>
      </body>
    </html>
  );
};

export default GlobalError;

What just happened: Because global-error.tsx replaces the entire root layout when it triggers, it has to define its own <html> and <body> tags — your normal fonts, providers, and navigation won't be available. Keep this file as simple and dependency-free as possible, since if the root layout crashed, you can't assume anything else in your app still works.

💡 Tip: For most apps, you'll rarely see global-error.tsx fire — root layout crashes are uncommon. But always keep the file in place as a safety net so users never see a completely broken, unstyled page.

Step 3: Handle "Not Found" Cases

A 404 happens when a user hits a URL that doesn't exist, or when you explicitly know a resource is missing (like a product ID that doesn't exist in your database). Next.js 16 gives you two files for this.

`not-found.tsx` for a Specific Segment

// app/blog/[slug]/not-found.tsx
const PostNotFound = () => {
  return (
    <div className="p-10 text-center">
      <h2 className="text-2xl font-bold">Post not found</h2>
      <p className="text-gray-500">This blog post doesn&apos;t exist or was removed.</p>
    </div>
  );
};

export default PostNotFound;

Trigger it explicitly by calling the notFound() function anywhere in a Server Component:

// app/blog/[slug]/page.tsx
import { notFound } from "next/navigation";
import { getPostBySlug } from "@/lib/posts";

interface Props {
  params: Promise<{ slug: string }>; // params is always a Promise in Next.js 16
}

const BlogPostPage = async ({ params }: Props) => {
  const { slug } = await params; // must be awaited
  const post = await getPostBySlug(slug);

  if (!post) {
    notFound(); // renders the nearest not-found.tsx
  }

  return <article>{post.content}</article>;
};

export default BlogPostPage;

What just happened: notFound() throws a special signal that Next.js catches internally and renders the closest not-found.tsx up the tree — similar to how error.tsx catches thrown errors, but specifically for missing content. It also correctly returns a 404 HTTP status, which matters for SEO.

`global-not-found.tsx` for Unmatched URLs (New in Next.js 16)

If someone visits a URL that doesn't match any route at all — a typo, an old bookmarked link — Next.js needs a catch-all 404 page for your whole app. In most apps, a root-level app/not-found.tsx already handles this. But if your app has multiple root layouts (like separate (admin) and (shop) groups) or a root layout built on a dynamic segment like app/[country]/layout.tsx, there's no single layout to render a 404 through — which is exactly the gap global-not-found.tsx closes.

First, enable it in your config:

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

const nextConfig: NextConfig = {
  experimental: {
    globalNotFound: true,
  },
};

export default nextConfig;

Then create the file at the root of app/:

// app/global-not-found.tsx
const GlobalNotFound = () => {
  return (
    <html>
      <body>
        <div style={{ textAlign: "center", padding: "3rem" }}>
          <h1>404 — Page not found</h1>
          <p>The page you&apos;re looking for doesn&apos;t exist.</p>
        </div>
      </body>
    </html>
  );
};

export default GlobalNotFound;

⚠️ Common Mistake: Like global-error.tsx, this file renders outside your normal root layout, so it needs its own <html> and <body> tags too.

Step 4: Handle Errors in Server Actions

Server Actions are trickier than page rendering — a thrown error there doesn't show your error.tsx UI cleanly, it just rejects the promise. The production-safe pattern is to avoid throwing for expected failures such as validation errors, and instead return a typed result the client can check.

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

import { z } from "zod";
import { db } from "@/lib/db";
import { updateTag } from "next/cache";

const CreatePostSchema = z.object({
  title: z.string().min(1, "Title is required"),
  body: z.string().min(1, "Body is required"),
});

export const createPost = async (_prev: unknown, formData: FormData) => {
  const parsed = CreatePostSchema.safeParse({
    title: formData.get("title"),
    body: formData.get("body"),
  });

  if (!parsed.success) {
    return { error: parsed.error.flatten().fieldErrors };
  }

  try {
    const post = await db.post.create({ data: parsed.data });
    updateTag("posts"); // instantly reflects the new post
    return { data: post };
  } catch (err) {
    console.error("Failed to create post:", err);
    return { error: { _form: ["Something went wrong. Please try again."] } };
  }
};

Then consume it on the client with useActionState:

// app/posts/_new-post-client.tsx
"use client";

import { useActionState } from "react";
import { createPost } from "@/actions/posts";

export const NewPostForm = () => {
  const [state, formAction, isPending] = useActionState(createPost, null);

  return (
    <form action={formAction} className="flex flex-col gap-3">
      <input name="title" placeholder="Title" className="border p-2" />
      {state?.error && "title" in state.error && (
        <p className="text-sm text-red-500">{state.error.title?.[0]}</p>
      )}

      <textarea name="body" placeholder="Body" className="border p-2" />

      <button disabled={isPending} className="rounded-md bg-black px-4 py-2 text-white">
        {isPending ? "Publishing..." : "Publish"}
      </button>
    </form>
  );
};

What just happened: safeParse validates the form data with Zod before it ever touches your database — this catches bad input early and cheaply. The try/catch around the database call handles unexpected failures (a dropped connection, a constraint violation) and turns them into a friendly { error } object instead of an unhandled crash. useActionState gives you state (the last returned value), formAction (to bind to the form), and isPending (to disable the button while submitting) — all without extra useState boilerplate.

💡 Tip: The rule of thumb: validation errors and expected failures → return { error }. Truly unexpected, unrecoverable errors → let them throw so Next.js's error boundary can catch them upstream.

Step 5: Handle Errors in Route Handlers (API Routes)

Route Handlers don't have an error boundary at all — if you don't catch an error yourself, the client just gets a generic 500 response with no useful detail.

// app/api/posts/route.ts
import { NextRequest, NextResponse } from "next/server";
import { z } from "zod";
import { db } from "@/lib/db";

const PostSchema = z.object({
  title: z.string().min(1),
  body: z.string().min(1),
});

export const POST = async (req: NextRequest) => {
  try {
    const body: unknown = await req.json();
    const parsed = PostSchema.safeParse(body);

    if (!parsed.success) {
      return NextResponse.json(
        { error: parsed.error.flatten() },
        { status: 400 },
      );
    }

    const post = await db.post.create({ data: parsed.data });
    return NextResponse.json(post, { status: 201 });
  } catch (err) {
    console.error("POST /api/posts failed:", err);
    return NextResponse.json(
      { error: "Internal server error" },
      { status: 500 },
    );
  }
};

What just happened: Every branch returns a proper NextResponse with an accurate status code — 400 for bad input the client sent, 500 for something that broke on your end. Wrapping the whole handler body in try/catch means a database outage returns a clean JSON error instead of the request just hanging or crashing the server process.

💡 Tip: Reserve 4xx responses for problems caused by the client (validation, authentication, missing resources) and 5xx responses for unexpected server failures. This distinction makes your API easier to debug and integrates better with monitoring systems.

⚠️ Common Mistake: Returning err.message directly to the client in the 500 response. Internal error messages can leak details about your database or file structure — log the real error server-side, and send the client a generic message.

Frequently Asked Questions

Does `error.tsx` catch errors in event handlers, like an `onClick`?

No. Error boundaries only catch errors thrown during rendering — not inside event handlers, setTimeout callbacks, or async code running after the render finished. Wrap those in a regular try/catch inside the handler itself.

Can `error.tsx` be a Server Component?

No, it must always start with "use client". React error boundaries are a client-side concept, and Next.js enforces this at build time.

What's the actual difference between `error.tsx` and `not-found.tsx`?

error.tsx catches unexpected thrown errors — bugs, failed fetches, crashes. not-found.tsx is for the expected case of "this specific thing doesn't exist," triggered on purpose by calling notFound(). Different problem, different UI, different HTTP status code.

Do I need `global-error.tsx` if I already have `error.tsx` everywhere?

Yes, keep it. error.tsx files can't catch errors thrown in the root layout itself (things like a provider that crashes on init), since the root layout wraps every error.tsx boundary you have.

💡 Tip: Think of it like a fuse box — error.tsx protects individual circuits (routes), while global-error.tsx is the master breaker for the whole house.

Should I use Sentry or a similar tool instead of just `console.error`?

For production apps, yes. console.error inside error.tsx is a starting point, but without a monitoring service you won't know an error happened until a user complains. Most teams call Sentry.captureException(error) (or an equivalent) inside the useEffect in error.tsx, and wrap Server Actions with the framework's server-action instrumentation to link client and server error traces together.

Wrapping Up

You now know how to scope error boundaries with error.tsx, catch root-layout crashes with global-error.tsx, handle missing content with not-found.tsx and the new global-not-found.tsx, and return safe, typed errors from Server Actions and Route Handlers instead of letting them crash silently. Put these in place before you need them — retrofitting error handling after a production incident is a much worse day than setting it up now.

Next, it's worth pairing this with proper loading states — Next.js Rendering Strategies Explained covers Suspense streaming so your loading and error boundaries work together for a fully resilient UI.

Continue Learning

Route Handlers Explained in Next.js 16 (Beginner's Guide) — goes deeper into building typed API endpoints, the same ones you're wrapping in try/catch in Step 5.
Next.js Rendering Strategies Explained: SSR, SSG, CSR, ISR & Cache Components (2026) — pairs naturally with error boundaries since Suspense streaming and error handling are designed to work together.
Next.js 16 Routing Explained: A Complete Beginner's Guide (2026) — covers how error.tsx, not-found.tsx, and other special files fit into the App Router's file-system conventions.
Zod vs Yup in 2026: Which Validation Library Should You Use? — if you want a deeper look at the safeParse validation pattern used in the Server Actions example above.

DEV Community: Syed Muhammad Ali

Next.js Adoption Benchmark 2026: The Data

Why an Adoption Benchmark, Not Just Another "vs" Post

Methodology: Where This Data Actually Comes From

Key Finding 1: Downloads and Stars — Next.js's Lead Is Still Large

Key Finding 2: Why This Post Doesn't Include a Multi-Year Download Chart

Key Finding 3: Survey Usage Confirms the Same Pattern, From a Different Angle

Key Finding 4: Usage Is High, Satisfaction Is a Genuinely Mixed Story

Key Finding 5: Server Components Adoption Still Has Real Room to Grow

An Original Composite View: The DevStacked Adoption Index

What This Actually Means If You're Choosing a Framework Right Now

Limitations of This Benchmark

Frequently Asked Questions

Is Next.js actually declining in popularity in 2026?

Why do npm download numbers for Next.js vary so much between sources?

Why do Stack Overflow and State of JS report such different usage percentages for Next.js?

Should low satisfaction scores stop me from choosing Next.js for a new project?

Is Astro a real threat to Next.js's dominance?

How often should a benchmark like this be updated?

Wrapping Up

Continue Learning

Sources

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

What Is Authentication? A Beginner's Guide (2026)

What Is Authentication? (Quick Answer)

Why Authentication Matters

Authentication vs. Authorization: The Difference That Trips Everyone Up

How Authentication Works (Step by Step)

The Main Types of Authentication

1. Password-Based Authentication

2. Session-Based Authentication

3. Token-Based Authentication (JWT)

4. OAuth / OpenID Connect (Social Login)

5. Multi-Factor Authentication (MFA / 2FA)

6. Passwordless Authentication (Magic Links & Passkeys)

A Minimal Authentication Flow in Next.js

Common Authentication Mistakes to Avoid

Frequently Asked Questions

What is the difference between authentication and authorization?

Is a login system the same thing as authentication?

What's the difference between sessions and JWTs?

Do I need a library to build authentication, or can I build it myself?

Is two-factor authentication (2FA) actually necessary?

Are passkeys better than passwords?

Wrapping Up

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 5: Understand `pending_reason` and `failure_reason`

Step 6: Listen for `refund.created`, `refund.updated`, and `refund.failed`