DEV Community: Syed Muhammad Ali

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.

Zod vs Yup in 2026: Which Validation Library Should You Use?

Syed Muhammad Ali — Sun, 02 Aug 2026 06:03:16 +0000

You've got a signup form. Email, password, maybe a checkbox for terms and conditions. Simple, right? Then someone submits email: 123 and your API route crashes with a cryptic error three files deep, because nothing ever checked that the data coming in actually matched what your code expected.

That's the exact gap schema validation libraries fill — and if you've searched for one, you've almost certainly landed on two names: Zod and Yup. Both let you describe the shape of your data once and validate real values against it. Both work great with React Hook Form. Both have been around long enough to be genuinely production-tested.

But they're not interchangeable, and picking the wrong one for your setup means either fighting TypeScript for months or hand-writing types you shouldn't have to. By the end of this guide, you'll know exactly how Zod and Yup differ, see real code for both, and know which one actually fits your project — not just which one has more GitHub stars.

Quick Answer

Choose Zod if you're using TypeScript and want your schema to be your type — no writing an interface separately and hoping it stays in sync.
Choose Yup if you're maintaining an existing Formik-based codebase, or your team is more comfortable with its .shape() API and mature async validation methods.

For any brand-new TypeScript project in 2026, Zod is the safer long-term default — it's what most modern tools (React Hook Form, tRPC, Next.js Server Action patterns) assume you're using. Now let's get into why.

What Is Schema Validation, Exactly?

Before comparing the two, a quick beginner-friendly definition: a schema is just a description of what your data should look like — "this field is a string," "this field is a number between 1 and 100," "this field is a valid email." A validation library takes that schema and checks real, incoming data (a form submission, an API request body) against it, telling you exactly what's wrong if it doesn't match.

Without one, you end up writing manual checks like this everywhere:

if (typeof data.email !== "string" || !data.email.includes("@")) {
  throw new Error("Invalid email");
}

Multiply that across every field, every form, every API route, and it gets messy fast — inconsistent error messages, duplicated logic, and no single source of truth for what "valid" even means. Zod and Yup both solve this by letting you define the rules once and reuse them everywhere.

Zod: TypeScript-First Validation

Zod was built specifically for TypeScript projects. Its core idea: you write one schema, and Zod derives both the runtime validator and the TypeScript type from it — there's no second place to keep in sync.

Installing Zod

npm install zod

A Basic Zod Schema

// lib/validators/user-schema.ts
import { z } from "zod";

export const userSchema = z.object({
  name: z.string().min(2, "Name must be at least 2 characters"),
  email: z.email("Please enter a valid email address"),
  age: z.number().int().positive().optional(),
  website: z.url().optional(),
});

// The type is derived directly from the schema — never written twice
export type User = z.infer<typeof userSchema>;

What's happening here: z.object({...}) describes the shape. z.email() and z.url() are Zod's built-in format validators (as of Zod v4, these live as top-level helpers rather than chained .email() string methods, though the chained form still works). z.infer<typeof userSchema> pulls a real TypeScript type straight out of the schema — if you add a field to the schema, the User type updates automatically, with zero manual work.

💡 Tip: This is Zod's single biggest selling point. You will never end up with a TypeScript interface that's quietly out of sync with your actual validation rules, because there's only one definition.

Validating Data with Zod

// Somewhere handling a form submission or API request
const result = userSchema.safeParse({
  name: "Ali",
  email: "not-an-email",
});

if (!result.success) {
  console.log(result.error.flatten().fieldErrors);
  // { email: ["Please enter a valid email address"] }
} else {
  // result.data is fully typed as `User`
  console.log(result.data.name);
}

What's happening here: safeParse() never throws — it returns a { success: true, data } or { success: false, error } object, so you don't need a try/catch block for normal validation flow. error.flatten().fieldErrors gives you a clean, per-field map of error messages, perfect for showing next to form inputs.

⚠️ Common Mistake: Using .parse() instead of .safeParse() in a code path where invalid data is expected (like a form submission). .parse() throws on failure, which means you need a try/catch everywhere — .safeParse() is almost always the better default for user input.

Zod in a Next.js Server Action

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

import { userSchema } from "@/lib/validators/user-schema";

export async function createUser(prevState: unknown, formData: FormData) {
  const result = userSchema.safeParse({
    name: formData.get("name"),
    email: formData.get("email"),
  });

  if (!result.success) {
    return { errors: result.error.flatten().fieldErrors };
  }

  // result.data is typed and safe to use here
  // await db.user.create({ data: result.data });

  return { success: true };
}

This is the exact pattern you'll see across most modern Next.js codebases — validate raw FormData on the server, never trust the client, and let the schema do the type narrowing for you.

Yup: The Established Forms Favorite

Yup predates the current TypeScript-first wave of tooling. It grew up alongside Formik and is still deeply embedded in a lot of React form codebases, particularly ones started before 2022.

Installing Yup

npm install yup

A Basic Yup Schema

// lib/validators/user-schema.ts
import * as yup from "yup";

export const userSchema = yup.object({
  name: yup.string().min(2, "Name must be at least 2 characters").required(),
  email: yup.string().email("Please enter a valid email address").required(),
  age: yup.number().integer().positive(),
  website: yup.string().url(),
});

// Yup's type inference — functional, but less precise than Zod's
export type User = yup.InferType<typeof userSchema>;

What's happening here: the shape looks similar to Zod at a glance, but notice .required() — in Yup, fields are optional by default unless you explicitly mark them required, which is the opposite of Zod's default (Zod fields are required unless you call .optional()). This trips up a lot of developers switching between the two.

⚠️ Common Mistake: Forgetting .required() on a Yup field and assuming it behaves like Zod. Yup schemas silently allow undefined on any field you don't explicitly mark required — this is one of the most common Yup-related bugs in production forms.

Validating Data with Yup

try {
  const validData = await userSchema.validate(
    { name: "Ali", email: "not-an-email" },
    { abortEarly: false }
  );
  console.log(validData);
} catch (err) {
  if (err instanceof yup.ValidationError) {
    console.log(err.errors); // ["Please enter a valid email address"]
  }
}

What's happening here: Yup's .validate() is async by default and returns a Promise — this is a real difference from Zod, where safeParse is synchronous unless you specifically opt into safeParseAsync. abortEarly: false tells Yup to collect every validation error instead of stopping at the first one. For a version that never throws, Yup also offers validateSync() with a try/catch, or you can check .isValid().

Yup in a Next.js Server Action

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

import { userSchema } from "@/lib/validators/user-schema";
import { ValidationError } from "yup";

export async function createUser(prevState: unknown, formData: FormData) {
  try {
    const data = await userSchema.validate(
      {
        name: formData.get("name"),
        email: formData.get("email"),
      },
      { abortEarly: false }
    );

    // await db.user.create({ data });
    return { success: true };
  } catch (err) {
    if (err instanceof ValidationError) {
      const fieldErrors: Record<string, string[]> = {};
      for (const e of err.inner) {
        if (e.path) fieldErrors[e.path] = [...(fieldErrors[e.path] ?? []), e.message];
      }
      return { errors: fieldErrors };
    }
    throw err;
  }
}

Notice this requires a try/catch and manually reshaping err.inner into a field-keyed object — Zod's flatten().fieldErrors gives you that shape for free.

Zod vs Yup: Side-by-Side

	Zod	Yup
TypeScript inference	Automatic, precise (`z.infer`)	Functional but looser (`InferType`)
Default field behavior	Required by default	Optional by default
Validation style	Sync by default (`safeParse`), async available	Async by default (`.validate()`)
Error shape	Structured `ZodError` with `.flatten()`	`ValidationError` with `.inner` array
Bundle size (gzipped)	Zod is slightly larger, but the difference is usually too small to matter for real applications.	Slightly smaller
React Hook Form support	✅ via `@hookform/resolvers/zod`	✅ via `@hookform/resolvers/yup`
Ecosystem fit	tRPC, modern Next.js patterns, Server Actions	Formik, legacy React form codebases
Learning curve	Slightly more API surface	Simpler, more forgiving for JS-first teams
Best for	New TypeScript projects	Existing Formik/Yup codebases

💡 Tip: Bundle size differences here are small enough that they shouldn't be your deciding factor for most apps — a few KB gzipped rarely matters next to your actual app code and images.

Using Either One with React Hook Form

This is where a lot of real-world decisions actually get made, so it's worth showing both side by side. Both integrate through the same @hookform/resolvers package.

npm install react-hook-form @hookform/resolvers

With Zod:

"use client";

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

const formSchema = z.object({
  email: z.email(),
  password: z.string().min(8, "Password must be at least 8 characters"),
});

type FormValues = z.infer<typeof formSchema>;

export function LoginForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<FormValues>({
    resolver: zodResolver(formSchema),
  });

  const onSubmit = (data: FormValues) => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("email")} />
      {errors.email && <p>{errors.email.message}</p>}

      <input type="password" {...register("password")} />
      {errors.password && <p>{errors.password.message}</p>}

      <button type="submit">Log in</button>
    </form>
  );
}

With Yup:

"use client";

import { useForm } from "react-hook-form";
import { yupResolver } from "@hookform/resolvers/yup";
import * as yup from "yup";

const formSchema = yup.object({
  email: yup.string().email().required(),
  password: yup.string().min(8, "Password must be at least 8 characters").required(),
});

type FormValues = yup.InferType<typeof formSchema>;

export function LoginForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<FormValues>({
    resolver: yupResolver(formSchema),
  });

  const onSubmit = (data: FormValues) => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("email")} />
      {errors.email && <p>{errors.email.message}</p>}

      <input type="password" {...register("password")} />
      {errors.password && <p>{errors.password.message}</p>}

      <button type="submit">Log in</button>
    </form>
  );
}

What's different: almost nothing at the React Hook Form layer — swap the resolver, swap the schema syntax, and everything else stays identical. This is exactly why the "which one" decision usually comes down to TypeScript ergonomics and team familiarity rather than form-library compatibility, since both are equally well supported.

Async Validation: Where Yup Still Has an Edge

If you need to check something against a server mid-validation — "is this username already taken?" — Yup's .test() method has had mature async support for years:

const signupSchema = yup.object({
  username: yup.string().test(
    "unique-username",
    "This username is already taken",
    async (value) => {
      if (!value) return true;
      const res = await fetch(`/api/check-username?u=${value}`);
      const { available } = await res.json();
      return available;
    }
  ),
});

Zod supports async refinements too, using .refine() with an async function and safeParseAsync():

const signupSchema = z.object({
  username: z.string(),
}).refine(
  async (data) => {
    const res = await fetch(`/api/check-username?u=${data.username}`);
    const { available } = await res.json();
    return available;
  },
  { message: "This username is already taken", path: ["username"] }
);

// must use safeParseAsync, not safeParse, when the schema has async refinements
const result = await signupSchema.safeParseAsync({ username: "ali" });

What's happening here: both libraries can do this — Yup's API was simply designed around async validation from the start, so it reads slightly more naturally. Zod requires you to remember to swap safeParse for safeParseAsync whenever an async .refine() is in play, which is an easy thing to forget.

⚠️ Common Mistake: Calling safeParse() (not safeParseAsync()) on a Zod schema with an async .refine(). It won't throw — it'll just resolve the refinement incorrectly, since Zod can't await inside a synchronous parse. Always match safeParseAsync to async refinements.

Migrating from Yup to Zod (If You're Considering It)

If you're weighing a migration, here's the honest advice: don't rewrite a working Yup codebase just to switch libraries. The type-safety gains are real, but they're not worth the regression risk on schemas that already work in production. Reach for Zod on new features or new projects instead, and let old Yup schemas retire naturally as you touch that code for other reasons.

If you are migrating a specific schema, the field-by-field mapping is usually mechanical:

Yup	Zod
`yup.string().required()`	`z.string()`
`yup.string().optional()`	`z.string().optional()`
`yup.string().email()`	`z.email()`
`yup.number().integer()`	`z.number().int()`
`yup.object().shape({...})`	`z.object({...})`
`yup.InferType<typeof schema>`	`z.infer<typeof schema>`

Frequently Asked Questions

Can I use Zod without TypeScript?

Yes, Zod works fine in plain JavaScript — but you lose its single biggest advantage, since type inference only matters if you have TypeScript to infer into. If your project is JavaScript-only, Zod and Yup are much closer in practical value, and team familiarity should decide it.

Is Zod always faster than Yup?

Not necessarily, and it depends heavily on the shape of your schema. For most typical form-sized payloads, both validate in well under a millisecond, so raw performance differences almost never matter in practice — TypeScript ergonomics and API fit are the more meaningful factors.

Do I need to rewrite my Formik forms to use Zod?

No. Formik and Yup are still a perfectly fine, actively maintained combination for existing codebases. Only reach for a migration if you're already refactoring that form layer for other reasons.

Which one works better with tRPC?

Zod, by a wide margin — tRPC's input/output validation is built with Zod's type inference in mind, and most tRPC examples and starter templates assume Zod. Yup can technically be adapted, but it's fighting the grain.

Can I use both Zod and Yup in the same project?

Technically yes, but it's not something to do on purpose. If you're migrating incrementally, it's fine to have both installed temporarily — just avoid mixing them within the same feature or form, since their default behaviors (required vs. optional fields, sync vs. async) differ enough to cause confusing bugs.

Does Zod support transforming data, not just validating it?

Yes — .transform() lets you reshape data as part of validation, like converting a string date into a Date object. Yup supports this too, through .transform() on its schemas. Both are equally capable here.

Wrapping Up

Zod and Yup solve the exact same problem — turning "hope the data is right" into "know the data is right" — but they were built for different eras of the JavaScript ecosystem. Zod's schema-is-the-type approach is what modern TypeScript tooling expects in 2026, and it's the right default for anything new you're building. Yup remains a completely legitimate choice if you're maintaining an existing Formik-based app, and there's no urgency to rip it out just because a newer library exists.

If you're starting a project today: reach for Zod, pair it with @hookform/resolvers/zod for your forms, and use .safeParse() on the server inside every Server Action or API route that touches user input — never trust that client-side validation alone is enough.

Try This Free Developer Tool

Zod Schema Generator — paste a JSON sample or a TypeScript interface and get a production-ready Zod schema instantly, complete with smart field-name inference, a live validator, and ready-to-use React Hook Form, API Route, and Server Action output.

Continue Learning

Google Tag Manager & GA4 Setup for Next.js 16 (2026 Guide)

Syed Muhammad Ali — Sat, 01 Aug 2026 19:00:00 +0000

You finally got Google Search Console wired up and Google is crawling your site properly. Great — now you have zero idea what any of those visitors actually do once they land. Which pages do they bounce from? Did that "Subscribe" button you spent an hour styling get clicked even once this week? Search Console tells you how people find you. It says nothing about what happens next.

That's the gap Google Tag Manager (GTM) and Google Analytics 4 (GA4) fill — and in Next.js 16, setting both up correctly gives you a scalable analytics setup that can grow from a single GA4 tag to dozens of marketing and analytics integrations without changing your application code.

By the end of this guide, you'll have GTM installed the right way in the App Router, a GA4 property receiving real pageview data through GTM (not directly — there's a reason for that), a custom event tracked on a real button click, correct SPA pageview tracking for client-side navigations, and a working setup for Google's Consent Mode so you're not silently breaking analytics for EU visitors.

GTM vs. GA4: Get This Straight First

This trips up almost every beginner, so let's clear it up before touching any code.

Google Analytics (GA4) is the tool that actually shows you data — pageviews, events, audiences, conversion reports. It's the dashboard.
Google Tag Manager (GTM) is a container that delivers tags (tracking scripts) to your site — GA4, Google Ads conversion tracking, Meta Pixel, Hotjar, whatever you need — without you editing code every time marketing asks for a new pixel.

💡 Tip: Think of GTM as a delivery truck and GA4 as one of the packages it drops off. You could skip the truck and hand-deliver the GA4 package yourself (install GoogleAnalytics directly), but the moment you need a second or third tracking tool, you're stuck editing your codebase for every marketing request instead of adding a tag in a dashboard.

This guide sets it up the recommended way: GTM as the single container, GA4 wired inside GTM — not both installed side by side. Running GA4 twice (once directly, once through GTM) is one of the most common setup mistakes, and it silently doubles your pageview counts.

Why This Is Tricky in Next.js

Google's own install instructions assume a plain HTML site with a <head> and <body> you can paste a script into. Next.js's App Router doesn't work that way — you don't have a raw <head> tag to paste scripts into by hand, and doing it wrong can hurt your Core Web Vitals (specifically INP, since analytics scripts run JavaScript on every page).

The fix is @next/third-parties — an official Next.js package built specifically for this. It handles script loading strategy and script placement for you, so you don't have to reverse-engineer Google's raw <script> snippet into a Server Component. It does not, however, handle SPA pageview tracking for GTM automatically — more on that in Step 8.

Quick Comparison

Feature	GTM	GA4
Tracks visitors	❌	✅
Loads scripts	✅	❌
Dashboard	❌	✅
Events	via tags	stores events

Prerequisites

This guide uses:

Next.js 16 with the App Router
TypeScript in strict mode
A Google account (the same one you used for Search Console works fine)

You don't need a GA4 property or GTM container yet — we'll create both from scratch.

Step 1: Create a GTM Container

Head to tagmanager.google.com and sign in.

Click Create Account
Account name: your site or company name (e.g. "DevStacked")
Country: your country
Container name: your domain (e.g. devstacked.tech)
Target platform: choose Web
Click Create, accept the Terms of Service

You'll land on your container's workspace and see a Container ID in the top right that looks like GTM-XXXXXXX. That's the only value you need to copy right now.

⚠️ Common Mistake: Google shows you an install snippet with two <script> blocks (one for <head>, one for <body>) right after creating the container. Ignore both of them — that's the plain-HTML method. In Next.js, @next/third-parties replaces this entirely, and pasting Google's raw snippet into your layout can actually break hydration.

Step 2: Create a GA4 Property

Head to analytics.google.com and sign in with the same account.

Click Admin (the gear icon, bottom left)
Under the Account column, click Create Account (or select an existing one)
Fill in an account name, then click Next
Under Property, enter a property name, your timezone, and currency
Fill in basic business details, then click Create
Under Data Streams, choose Web
Enter your site's URL and a stream name, then click Create stream

You'll now see a Measurement ID that looks like G-XXXXXXXXXX. Copy that too — you'll paste it into GTM, not directly into your Next.js code.

💡 Tip: A GA4 "property" is the whole analytics dataset. A "data stream" is one source feeding it — your website in this case. You can add more streams (an iOS app, for example) to the same property later, and they'll all roll up into one set of reports.

Step 3: Install GTM in Next.js with `@next/third-parties`

Install the package (it may already be installed if you're on a recent Next.js scaffold — check package.json first):

npm install @next/third-parties@latest next@latest

What's happening here: @next/third-parties is an official Next.js package, maintained by the Next.js team, that wraps common third-party scripts (GTM, GA4, YouTube embeds, Google Maps) in components tuned for App Router's rendering and script-loading behavior — so you get the right strategy on the underlying next/script call without configuring it yourself.

Add the container to your root layout:

// app/layout.tsx
import { GoogleTagManager } from "@next/third-parties/google";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <GoogleTagManager gtmId="GTM-XXXXXXX" />
      <body>{children}</body>
    </html>
  );
}

What's happening here: <GoogleTagManager /> renders GTM's script tags in the right place and loads them with a strategy that doesn't block your page's initial render. Placing it as a direct child of <html>, alongside <body>, matches Next.js's own documented pattern — the component internally handles inserting the <noscript> iframe fallback GTM needs for users with JavaScript disabled, so you don't add that by hand.

Don't hardcode the container ID directly in the file — pull it from an environment variable instead, so staging and production can use different containers if you ever need that:

# .env.local
NEXT_PUBLIC_GTM_ID=GTM-XXXXXXX

// app/layout.tsx
<GoogleTagManager gtmId={process.env.NEXT_PUBLIC_GTM_ID!} />

⚠️ Common Mistake: Forgetting the NEXT_PUBLIC_ prefix. Without it, the variable only exists on the server and comes through as undefined in the browser — GTM ID values aren't sensitive, so NEXT_PUBLIC_ is the correct and required prefix here.

Deploy this change. GTM data won't show up instantly — give it a few minutes after your first real page load in production.

Step 4: Add GA4 as a Tag Inside GTM

This is the step most tutorials skip or get backwards. Don't install <GoogleAnalytics gaId="G-XXXXXXXXXX" /> directly in your layout — configure GA4 as a tag inside GTM instead, so GTM stays your single source of truth for every tracking script.

Back in your GTM workspace:

Click Tags in the left sidebar → New
Click the tag configuration box → choose Google Analytics: GA4 Configuration
Paste your Measurement ID (G-XXXXXXXXXX) from Step 2
Under Triggering, click the trigger box → choose All Pages (a built-in trigger that fires once, on the initial load)
Name the tag something clear, like GA4 - Config
Click Save

What's happening here: this tag tells GTM "initialize GA4 with this Measurement ID and send a pageview." It also turns on GA4's Enhanced Measurement, a set of features enabled by default in every new GA4 property — one of which listens for browser history changes (pushState/replaceState) and can send a page_view on its own when the URL changes without a full reload. That's genuinely useful, because it means client-side navigations in Next.js might already be tracked correctly with nothing further to do. Whether that's actually true for your setup is what Step 8 checks.

Publish the Container

Nothing goes live until you publish. In the top right of GTM, click Submit → give the version a name (e.g. "Add GA4 config tag") → Publish.

⚠️ Common Mistake: Editing tags in GTM and expecting them to work immediately. Changes only take effect after you click Submit → Publish — the workspace view is always a draft until then.

Step 5: Verify It's Actually Working

Don't just assume it works — confirm it, in two places.

GTM Preview Mode

In your GTM workspace, click Preview in the top right. Enter your site's URL (http://localhost:3000 works fine for local testing) and click Connect. This opens a debug panel showing every tag that fires as you navigate your site in real time — you should see your GA4 - Config tag firing on Page View events.

GA4 Realtime Report

In GA4, go to Reports → Realtime. Open your site in another tab and click around. You should see yourself show up as an active user within a few seconds.

💡 Tip: If Preview mode shows the tag firing but GA4 Realtime shows nothing, double-check the Measurement ID was pasted correctly into the GTM tag — a single typo'd character is the most common cause of "everything looks connected but no data arrives."

Step 6: Track a Custom Event (Button Click)

Pageviews tell you traffic. Events tell you what people actually do — clicking "Subscribe," submitting a contact form, opening a pricing tab. Here's how to send a real custom event from a Next.js component into GTM, then forward it to GA4.

Send the Event from Your Component

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

import { sendGTMEvent } from "@next/third-parties/google";

export function NewsletterButton() {
  const handleClick = () => {
    sendGTMEvent({ event: "subscribe_newsletter", value: "footer_cta" });
  };

  return (
    <button onClick={handleClick} className="rounded-lg bg-primary px-4 py-2 text-white">
      Subscribe
    </button>
  );
}

What's happening here: sendGTMEvent() pushes an object onto GTM's dataLayer — an internal array GTM constantly watches for new entries. The event: "subscribe_newsletter" key is what GTM matches against a trigger; any other keys (value here) become extra data you can reference later. This must run in a Client Component ("use client") since it fires on a real browser click.

⚠️ Common Mistake: Calling sendGTMEvent() in a component that never actually renders inside a page where <GoogleTagManager /> is present in a parent layout. If GTM's script hasn't loaded on that route, the event silently goes nowhere — since our GTM component sits in the root layout, every route is covered, but double-check if you ever load GTM per-page instead of globally.

Create a Trigger in GTM

In GTM, click Triggers → New
Choose trigger type Custom Event
Event name: subscribe_newsletter (must match exactly, including case)
Name it (e.g. Trigger - Subscribe Click) and Save

Create a GA4 Event Tag

Click Tags → New
Tag type: Google Analytics: GA4 Event
Configuration Tag: select your GA4 - Config tag from Step 4 (this reuses the same Measurement ID instead of re-entering it)
Event Name: subscribe_newsletter
Under Triggering, select the Trigger - Subscribe Click trigger you just made
Save, then Submit → Publish

Click the button on your live site, check GTM Preview mode for the event firing, then check GA4 under Reports → Realtime → Event count by Event name to confirm it shows up.

Step 7: Set Up Consent Mode (Don't Skip This)

If any visitors are in the EU/EEA/UK, you're generally required to get consent before running non-essential tracking cookies like GA4's. Google's Consent Mode lets GTM/GA4 adjust their behavior based on what a user actually agreed to, instead of firing full tracking regardless of consent — which is both a compliance risk and, without Consent Mode, a hole in your data (GA4 can still model some conversions from consent-denied users with Consent Mode enabled; without it, you get nothing from those visitors).

The mechanics: before GTM's script even loads, you set a default consent state (usually "denied" until the user chooses), then update it once they interact with your cookie banner.

// app/layout.tsx
import Script from "next/script";
import { GoogleTagManager } from "@next/third-parties/google";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <Script id="consent-default" strategy="beforeInteractive">
        {`
          window.dataLayer = window.dataLayer || [];
          function gtag(){dataLayer.push(arguments);}
          gtag('consent', 'default', {
            'ad_storage': 'denied',
            'analytics_storage': 'denied',
            'wait_for_update': 500
          });
        `}
      </Script>
      <GoogleTagManager gtmId={process.env.NEXT_PUBLIC_GTM_ID!} />
      <body>{children}</body>
    </html>
  );
}

What's happening here: strategy="beforeInteractive" from next/script guarantees this consent-default script runs before GTM's own script executes, which is required — Consent Mode only works if the default state is set first. wait_for_update: 500 tells Google's tags to wait up to 500ms for a real consent decision (from your cookie banner) before falling back to the denied default.

When your cookie banner records a user's choice, call the same gtag() function again with 'update' instead of 'default' — it's the same lightweight stub defined in the script above, attached to window, so any client component can call it later:

// After the user clicks "Accept" in your cookie banner
window.gtag?.("consent", "update", {
  ad_storage: "granted",
  analytics_storage: "granted",
});

💡 Tip: Keep the update call in the same gtag(...) form as the default call above rather than pushing a raw array to dataLayer directly. Both work — gtag() here is just function gtag(){dataLayer.push(arguments)} — but sticking to one form avoids making readers wonder whether they're two different APIs.

⚠️ Common Mistake: Setting up a cookie banner UI but never actually calling consent update when the user clicks accept. Without this call, GTM stays permanently in denied mode and you collect essentially no analytics data, even from users who were fine with tracking.

💡 This guide covers the mechanics of wiring Consent Mode into GTM — pair it with a real cookie-consent banner library (or your own) that actually detects EU/UK visitors and blocks the page until a choice is made if your legal requirements call for that.

Step 8: Verify (and Fix, If Needed) Route Change Tracking

This is the step where most GTM + Next.js guides get sloppy, so let's be precise about it.

GTM itself doesn't understand Next.js routing. It's just a container — it has no built-in concept of client-side navigation. But that doesn't automatically mean pageviews break. The GA4 - Config tag from Step 4 turns on GA4's Enhanced Measurement, and Enhanced Measurement's history-based page tracking is a feature of the GA4 library itself, not something GTM adds on top. So in a lot of setups, client-side navigations already get tracked correctly with zero extra work — you have to verify it, not assume either outcome.

First: Check Whether You Even Need This Step

Open GTM Preview mode and connect it to your site
Click around between a few different pages using real Next.js <Link> navigation (not a hard refresh)
In the Preview debug panel, watch for a gtm.historyChange-v2 (or gtm.historyChange) event firing on each navigation, immediately followed by your GA4 - Config tag
Cross-check in GA4 → Reports → Realtime → Event count by Event name — you should see a fresh page_view for each page you visited, not just the first one

If that's what you see, you're done — Enhanced Measurement is already handling it, and nothing else in this step applies to you.

💡 Tip: "Page changes based on browser history events" is the setting responsible for this, and it's on by default. You can find it under GA4 → Admin → Data Streams → your web stream → Enhanced Measurement → (gear icon) → Page views. Confirm it's checked before assuming it's broken.

If It's Not Firing Reliably

Some SPA routing patterns don't dispatch history events in a way Enhanced Measurement's listener reliably picks up, and Next.js's App Router is one of the setups worth testing carefully rather than assuming either way. If Step 8's check above came back with missing or inconsistent page_view events, here's the fix — following Google's own documented pattern for measuring SPAs with GTM, not a repeat of the Configuration tag.

1. Turn off Enhanced Measurement's history tracking so it stops competing with the manual setup below: GA4 → Admin → Data Streams → your web stream → Enhanced Measurement → (gear icon) → Page views, uncheck Page changes based on browser history events.

2. Create a History Change trigger in GTM:

Triggers → New → trigger type History Change
Name it Trigger - SPA Pageview, Save

3. Create a separate GA4 Event tag — don't add this trigger to the Configuration tag itself:

Tags → New → tag type Google Analytics: GA4 Event
Configuration Tag: select your existing GA4 - Config tag (this reuses its Measurement ID without re-initializing GA4)
Event Name: page_view
Triggering: the Trigger - SPA Pageview trigger you just made
Name it GA4 - SPA Page View, Save, then Submit → Publish

Why a separate tag instead of re-firing the Configuration tag: the Configuration tag's job is to initialize GA4 once per page load — it's not designed to be re-triggered repeatedly. Google's own SPA measurement guide is explicit about this: create the History Change trigger, then fire a dedicated GA4 Event tag off it, referencing the Configuration tag rather than reusing it directly as the trigger target.

If GTM's History Change trigger still misses some router.push() navigations in testing (this does happen on certain SPA setups), the more reliable fallback is asking a developer to push the event manually instead:

// components/gtm-pageview-tracker.tsx
"use client";

import { usePathname, useSearchParams } from "next/navigation";
import { useEffect } from "react";
import { sendGTMEvent } from "@next/third-parties/google";

export function GtmPageviewTracker() {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useEffect(() => {
    const url = `${pathname}${searchParams.toString() ? `?${searchParams.toString()}` : ""}`;
    sendGTMEvent({ event: "spa_page_view", page_path: url });
  }, [pathname, searchParams]);

  return null;
}

Mount it once in the root layout, alongside {children}. Then in GTM, create a Custom Event trigger for spa_page_view and point your GA4 - SPA Page View tag at that trigger instead of History Change — everything else about the tag (Configuration Tag reference, page_view event name) stays the same.

⚠️ Common Mistake: Wiring up both the History Change trigger and the manual sendGTMEvent push to the same GA4 event tag, or forgetting to disable Enhanced Measurement's history tracking after adding either one. Any of these combinations double-fires page_view for the same navigation — pick exactly one source of truth for SPA pageviews.

The takeaway: don't reach for manual tracking by default. Verify first with GTM Preview and GA4 Realtime, and only build the History Change (or manual) setup if the default Enhanced Measurement behavior genuinely isn't covering your navigations.

Full Setup Checklist

[ ] GTM container created, ID copied (GTM-XXXXXXX)
[ ] GA4 property + web data stream created, Measurement ID copied (G-XXXXXXXXXX)
[ ] @next/third-parties installed
[ ] <GoogleTagManager gtmId={...} /> added as a sibling of <body> inside <html> in the root layout
[ ] GTM ID pulled from a NEXT_PUBLIC_ environment variable, not hardcoded
[ ] GA4 Configuration tag created inside GTM, triggered on All Pages
[ ] Container published (Submit → Publish), not left as a draft
[ ] Verified in GTM Preview mode and GA4 Realtime report
[ ] At least one custom event wired end-to-end (component → sendGTMEvent → GTM trigger → GA4 event tag)
[ ] Verified in GTM Preview + GA4 Realtime whether SPA route changes are already tracked by Enhanced Measurement — only added a History Change trigger or manual sendGTMEvent push if that check showed a real gap, never both at once
[ ] Consent Mode default state set with beforeInteractive, and a real consent update call wired to your cookie banner
[ ] No leftover GoogleAnalytics-style automatic pageview hooks running alongside your GTM setup (that's what causes double-counted pageviews)

Frequently Asked Questions

Should I install GA4 directly, or always go through GTM?

Go through GTM. Installing <GoogleAnalytics gaId="..." /> directly is fine for a tiny personal project that will never need another tracking tool, but the moment you want Google Ads conversion tracking, a Meta Pixel, or any other tag, you'll wish you'd started with GTM as the single container instead of managing multiple direct integrations in your codebase.

Why isn't data showing up in GA4 even though GTM Preview shows the tag firing?

Check three things in order: the Measurement ID was pasted correctly (no missing characters), the container was actually published (not left as a draft), and you're looking at Realtime, not the main reports — standard GA4 reports can take 24–48 hours to populate, but Realtime should update within seconds.

Do I need both GTM and Google Analytics accounts, or just one Google account?

Just one Google account — GTM and GA4 are separate products under the same Google login, so you don't need two different sign-ins. You will end up with a GTM container ID and a separate GA4 Measurement ID, which is expected.

Does adding GTM hurt my Core Web Vitals?

It can, if done wrong — GTM and any tags loaded inside it are extra JavaScript. @next/third-parties mitigates this with sensible load strategies out of the box, but every additional tag you add inside GTM (heatmaps, chat widgets, ad pixels) adds real weight. Periodically audit your GTM container and remove tags you're no longer using.

Can I test GTM/GA4 locally before deploying?

Yes — GTM Preview mode works against localhost directly, and you'll see tags firing in the debug panel without needing a live deployment. GA4 Realtime also picks up local traffic the same way it does production traffic, since it's just JavaScript running in your browser.

Does GTM need extra work for SPA pageviews that GA4-direct doesn't?

Not necessarily. GA4's automatic history-change tracking comes from Enhanced Measurement, a feature of the GA4 library itself — it's on by default whether GA4 loads directly or as a tag inside GTM, since GTM just delivers the same GA4 script either way. In practice this means a lot of GTM setups track SPA navigations correctly with no extra configuration. The only time you need the History Change trigger (or a manual sendGTMEvent push) from Step 8 is if you actually tested with GTM Preview + GA4 Realtime and found navigations weren't being picked up — treat it as a fix for a confirmed gap, not a mandatory step.

Do I still need Google Search Console if I have GA4?

Yes — they answer different questions. GSC tells you how Google finds and ranks your pages (impressions, search queries, indexing status). GA4 tells you what happens after someone arrives (behavior, events, conversions). If you haven't set up Search Console yet, see our Search Console guide first.

Wrapping Up

You now have Google Tag Manager installed the right way in Next.js 16 — as a single container in the root layout, with GA4 configured as a tag inside it rather than a second direct integration, a real custom event tracked end-to-end, confirmed SPA pageview tracking (with a fix on hand if Enhanced Measurement didn't already cover it), and Consent Mode wired up so you're not flying blind on EU traffic. From here, every future tracking tool — Google Ads, a heatmap tool, a Meta Pixel — gets added inside the GTM dashboard, not by touching your codebase again.

The natural next step is deciding which user actions actually matter for your site (signups, checkout starts, contact form submissions) and wiring each one up as its own sendGTMEvent() call, the same pattern used for the newsletter button above.

Continue Learning

Free SEO Tools

JSON-LD Generator for Next.js & HTML - generate Article, FAQ, Product, LocalBusiness, SoftwareApplication, Breadcrumb, Person, Organization, and Website JSON-LD — checked live against Google's actual Rich Results requirements.
Meta Tag Generator for Next.js & HTML — generate SEO meta tags, Open Graph tags, Twitter Cards, and canonical URLs instantly. Handy for wiring up per-post metadata like the generateMetadata() function above.
Supabase RLS Policy Generator — if your next project pairs this blog setup with a Supabase backend, generate secure, performance-optimized Row Level Security policies in seconds.
Zod Schema Generator — generate Zod schemas instantly from JSON or TypeScript. Includes smart inference, live validation, React Hook Form, Next.js API Routes, and Server Actions.

Supabase Auth vs Firebase Auth: Which One Should You Choose in 2026?

Syed Muhammad Ali — Thu, 30 Jul 2026 19:00:00 +0000

You're starting a new Next.js project, and before you write a single feature, you have to answer one boring but critical question: who's going to handle login?

Two names keep showing up at the top of every list — Supabase Auth and Firebase Auth. Both are free to start, both support Google/GitHub/email login, and both promise to save you from writing your own password-hashing logic. But they're built on completely different foundations, and picking the wrong one can mean months of awkward workarounds later — like discovering you need SQL joins for a permissions system, but you're stuck with Firestore's document model.

This guide breaks down exactly how Supabase Auth and Firebase Auth differ in 2026 — architecture, pricing, security, and real Next.js 16 App Router code for both — so you can pick the right one before you've built half your app on top of it.

Why This Comparison Is Tricky

Most "Supabase vs Firebase" posts compare marketing pages, not real implementation experience. The truth is these two products solve authentication very differently under the hood:

Supabase Auth is a layer on top of PostgreSQL — every user lives in a real SQL table (auth.users), and permissions are enforced with Row Level Security (RLS) policies written in SQL.
Firebase Auth is a layer on top of Firestore/Google Cloud — users live in Google's own auth system, and permissions are enforced with Firestore Security Rules, a completely different (non-SQL) rules language.

That single architectural difference is what actually decides which one fits your project — not the login form UI, which looks nearly identical on both.

Quick Answer

Choose Supabase Auth if you want a real Postgres database, SQL-based permissions (RLS), open-source flexibility, and the option to self-host later.
Choose Firebase Auth if you're already invested in Firebase or Google Cloud services, or if Firebase's managed identity infrastructure fits your application's architecture.

Now let's get into the details.

Supabase Auth vs Firebase Auth: Which Is Better for Next.js?

If you're building a Next.js SaaS application with PostgreSQL, Supabase Auth is usually the more natural choice because authentication, database access, and authorization can be designed around the same Postgres/RLS model.

Firebase Auth is a better fit when your application already uses Firebase/Google Cloud services or your data model naturally fits Firestore.

Supabase Auth vs Firebase Auth: Feature Comparison

Feature	Supabase Auth	Firebase Auth
Authentication architecture	Integrated with Supabase/PostgreSQL ecosystem	Managed identity service
Common database pairing	PostgreSQL	Firestore (NoSQL)
Free/no-cost auth tier	50,000 monthly active users (MAU)	Depends on Firebase Auth / Identity Platform configuration
Paid pricing	Included in Supabase plan quota; $0.00325/MAU over Pro quota	Identity Platform: 50,000 MAU no-cost tier on Blaze, then usage-based pricing
Email/password	✅	✅
Magic links	✅	✅ (email link sign-in)
Social OAuth (Google, GitHub, etc.)	✅	✅
Phone/SMS OTP	✅	✅
Permissions model	Row Level Security (SQL policies)	Firestore Security Rules (custom rules language)
Self-hosting	✅ Yes (fully open source)	❌ No
Open source	✅ Yes	❌ No
Next.js SSR package	`@supabase/ssr`	Firebase JS SDK + `initializeServerApp`
Best paired with	Postgres-based SaaS apps	Google Cloud / Firestore apps

💡 Tip: Both platforms' free tiers are generous enough to cover most side projects and early-stage SaaS apps completely — pricing usually isn't the deciding factor until you're well past MVP stage.

Architecture: The Real Difference

This is the part most comparison articles skip, and it's the one that actually matters.

Supabase Auth Runs on Postgres

When someone signs up with Supabase Auth, a row gets created in a special auth.users table inside your actual Postgres database. Every other table you create — profiles, posts, orders — can have a foreign key pointing straight at auth.users.id.

That means your permissions logic is just SQL:

-- Only let a user see their own orders
create policy "Users can view own orders"
on orders
for select
using (auth.uid() = user_id);

Why this matters: if your app has relational data — a user has many orders, an order has many line items, a team has many members — Postgres joins handle that naturally. You're not fighting the database to model relationships.

Firebase Auth And Firestore

Firebase Auth manages identity separately from your application data. When paired with Firestore, authorization is commonly enforced using Firestore Security Rules — a rules language, not SQL:

// firestore.rules
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /orders/{orderId} {
      allow read: if request.auth != null && request.auth.uid == resource.data.userId;
    }
  }
}

Why this matters: Firestore is a document database. There's no native JOIN. If your data is deeply relational (think: multi-tenant SaaS with teams, roles, and shared resources), you'll end up duplicating data across documents or running multiple round-trip queries to stitch things together client-side.

💡 Tip: Neither model is "wrong" — Firestore's document model is genuinely great for chat apps, real-time feeds, and simple per-user data. Postgres shines once your data has real relationships between tables.

Setting Up Supabase Auth in Next.js 16

This guide assumes Next.js 16 with the App Router, TypeScript in strict mode, and Tailwind CSS — the current defaults for any new Next.js project.

Step 1: Install Dependencies

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

What's happening here: @supabase/supabase-js is the core client library. @supabase/ssr is the package built specifically for frameworks like Next.js — it handles the tricky part of syncing auth cookies between the browser and the server so your session works correctly in Server Components, Server Actions, and the browser alike.

Step 2: Add Environment Variables

# .env.local
NEXT_PUBLIC_SUPABASE_URL=https://yourproject.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your_publishable_key

⚠️ Never expose a Supabase secret key (sb_secret_...) or legacy service_role key in client-side code. Both bypass RLS.

💡 Tip: For new Supabase projects, use the publishable key rather than the legacy anon key. Supabase is transitioning away from the legacy API keys during 2026.

Step 3: Create the Browser Client

// 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!
  );
}

Use this inside Client Components — anywhere you need "use client".

Step 4: Create the Server Client

// lib/supabase/server.ts
import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";

export async function createClient() {
  const cookieStore = await cookies();

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll();
        },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options)
            );
          } catch {
            // Safe to ignore when called from a Server Component
          }
        },
      },
    }
  );
}

What's happening here: this client reads and writes auth cookies through Next.js's cookies() API, so a session created during login is visible to Server Components and Server Actions immediately — no manual token passing needed.

Step 5: Add the Auth Proxy (Middleware)

// utils/supabase/proxy.ts
import { createServerClient } from "@supabase/ssr";
import { NextResponse, type NextRequest } from "next/server";

export async function updateSession(request: NextRequest) {
  let supabaseResponse = NextResponse.next({ request });

  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
    {
      cookies: {
        getAll() {
          return request.cookies.getAll();
        },
        setAll(cookiesToSet, headers) {
          cookiesToSet.forEach(({ name, value }) =>
            request.cookies.set(name, value)
          );
          supabaseResponse = NextResponse.next({ request });
          cookiesToSet.forEach(({ name, value, options }) =>
            supabaseResponse.cookies.set(name, value, options)
          );
          Object.entries(headers).forEach(([key, value]) =>
            supabaseResponse.headers.set(key, value)
          );
        },
      },
    }
  );

  await supabase.auth.getClaims();

  return supabaseResponse;
}

// proxy.ts (root of project)
import { type NextRequest } from "next/server";
import { updateSession } from "@/utils/supabase/proxy";

export async function proxy(request: NextRequest) {
  return await updateSession(request);
}

export const config = {
  matcher: [
    "/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
  ],
};

⚠️ Common Mistake: Skipping this proxy file. Without it, Supabase's refresh token doesn't get renewed on every request, and users get randomly logged out mid-session — one of the most common Supabase Auth bugs beginners hit.

Step 6: Sign In With Email and Password

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

import { redirect } from "next/navigation";
import { createClient } from "@/lib/supabase/server";

export async function login(prev: unknown, formData: FormData) {
  const supabase = await createClient();

  const { error } = await supabase.auth.signInWithPassword({
    email: formData.get("email") as string,
    password: formData.get("password") as string,
  });

  if (error) {
    return { error: error.message };
  }

  redirect("/dashboard");
}

Step 7: Protect Data with Row Level Security

This is Supabase Auth's biggest advantage — security lives at the database level, not just in your app code:

alter table profiles enable row level security;

create policy "Users can view own profile"
on profiles for select
using ((select auth.uid()) = id);

create policy "Users can update own profile"
on profiles for update
using ((select auth.uid()) = id)
with check ((select auth.uid()) = id);

Why this matters: even if someone bypasses your Next.js app entirely and hits the Supabase API directly, RLS still blocks them from seeing data that isn't theirs. Your frontend code stops being the only line of defense.

💡 If you're using Supabase Auth with multiple tables, writing RLS policies manually can become repetitive. DevStacked's Supabase RLS Policy Generator can generate strict policies based on your access pattern.

Setting Up Firebase Auth in Next.js 16

Step 1: Install Dependencies

npm install firebase firebase-admin

What's happening here: firebase is the client SDK (runs in the browser and in Server Components via Firebase's newer server app support). firebase-admin is for privileged, server-only operations like verifying tokens.

Step 2: Add Environment Variables

# .env.local
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=yourproject.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=yourproject

Step 3: Initialize Firebase (Client Side)

// lib/firebase/client.ts
import { initializeApp, getApps, getApp } from "firebase/app";
import { getAuth } from "firebase/auth";

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
};

const app = getApps().length ? getApp() : initializeApp(firebaseConfig);

export const auth = getAuth(app);

What's happening here: getApps().length ? getApp() : initializeApp(...) prevents Firebase from being re-initialized on every hot reload in development — a classic Firebase + Next.js gotcha if you skip this check.

Step 4: Sign In With Email and Password

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

import { signInWithEmailAndPassword } from "firebase/auth";
import { auth } from "@/lib/firebase/client";
import { useRouter } from "next/navigation";
import { useState } from "react";

export function LoginForm() {
  const router = useRouter();
  const [error, setError] = useState("");

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const form = new FormData(e.currentTarget);

    try {
      await signInWithEmailAndPassword(
        auth,
        form.get("email") as string,
        form.get("password") as string
      );
      router.push("/dashboard");
    } catch (err) {
      setError(err instanceof Error ? err.message : "Login failed");
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" type="email" required />
      <input name="password" type="password" required />
      <button type="submit">Sign in</button>
      {error && <p>{error}</p>}
    </form>
  );
}

⚠️ Common Mistake: Doing all your auth logic client-side and assuming that's enough for SSR. Firebase's client SDK doesn't automatically make the logged-in user visible to your Next.js Server Components — you need a separate step to bridge that gap (next).

Step 5: Bridge the Session to the Server

Firebase's newer Firebase Server App feature lets you read the authenticated user inside Server Components:

// lib/firebase/server.ts
import { cookies } from "next/headers";
import { initializeApp, initializeServerApp } from "firebase/app";
import { getAuth } from "firebase/auth";

export async function getAuthenticatedAppForUser() {
  const authIdToken = (await cookies()).get("__session")?.value;

  const firebaseServerApp = initializeServerApp(initializeApp(), {
    authIdToken,
  });

  const auth = getAuth(firebaseServerApp);
  await auth.authStateReady();

  return { firebaseServerApp, currentUser: auth.currentUser };
}

Learn more Firebase Server App here

What's happening here: the client sets a __session cookie containing the Firebase ID token after login (you write this cookie yourself, typically via a small API route or onIdTokenChanged listener). The server then rebuilds an authenticated Firebase app instance from that cookie — this is meaningfully more manual than Supabase's @supabase/ssr package, which handles cookie syncing for you out of the box.

Note: This example demonstrates the server-side bridge rather than a complete production session-cookie implementation. In production, use a secure HTTP-only session cookie and validate it server-side.

⚠️ Common Mistake: Assuming Firebase Auth "just works" with Server Components the way it works with a client-only SPA. The App Router's server/client split means you need this extra bridging step — it's the single biggest source of Firebase + Next.js App Router complaints online.

Step 6: Protect Data with Firestore Security Rules

// firestore.rules
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /profiles/{userId} {
      allow read, update: if request.auth != null && request.auth.uid == userId;
    }
  }
}

Firestore rules are enforced server-side by Google's infrastructure, similar in spirit to RLS — but written in a proprietary rules language instead of SQL, so there's a real learning curve if your team already knows SQL but not Firestore's rule syntax.

Pricing Comparison

	Supabase Auth	Firebase Auth
Free tier	50,000 MAU	Depends on Firebase Auth / Identity Platform configuration
Paid tier	Included in Supabase plan quota; additional MAU billed after quota	Usage-based pricing with Identity Platform
Self-hosting	✅ Available	❌ Not available

Both platforms offer generous options for early-stage projects, although the exact limits and pricing depend on the plan and services you use. The real cost difference shows up later: Supabase gives you a self-hosting escape hatch if you ever want to leave the MAU pricing model entirely; Firebase does not.

Security Considerations for Both

Regardless of which you choose, keep these in mind for Next.js 16:

Never trust client-side auth checks alone. Whether you're using Supabase or Firebase, always re-verify the session inside Server Actions and Route Handlers — a hidden button in the UI doesn't stop a direct API call.
proxy.ts (formerly middleware.ts) is a UX nicety, not your security boundary. Both Supabase's session refresh and any Firebase token check you add there can be bypassed by calling your backend directly — the real gate is the check inside your Server Action or database rule.
Default new users to the lowest-privilege role. Never let a signup form set its own role or is_admin field — assign it server-side.

When Should You Use Supabase Auth?

You want a real relational database (Postgres) under your app, not just auth.
Your app has complex relationships — teams, roles, shared resources, multi-tenancy.
You want the option to self-host later, or you like knowing you could.
You're already comfortable with SQL, or want to learn it.

When Should You Use Firebase Auth?

You're already using Firestore, Cloud Functions, Firebase Cloud Messaging, or Google Analytics.
Your data model is simple and document-shaped (a user has a profile, a handful of settings — no deep relational joins).
You want Google's massive scale and long production track record specifically for mobile + web apps together.
Your team already knows Firestore Security Rules.

Decision Table

If you need...	Better choice
Next.js + PostgreSQL	🟢 Supabase
SQL + relational data	🟢 Supabase
RLS-based authorization	🟢 Supabase
Self-hosting	🟢 Supabase
Firestore	🟢 Firebase
Firebase ecosystem	🟢 Firebase
Google Cloud integration	🟢 Firebase
Mobile + web Firebase stack	🟢 Firebase
Complex relational SaaS	🟢 Supabase
Document-oriented data	🟢 Firebase

Frequently Asked Questions

Can I switch from Firebase Auth to Supabase Auth later?

Yes, but it's real migration work. You'll need to migrate users and identities, account for password-hash compatibility and provider configuration, and rebuild authorization rules from your Firebase/Security Rules model into Supabase RLS.

Which one is easier for a complete beginner?

Firebase Auth's client-only setup (no SSR bridging) is slightly faster to get a basic login working. But Supabase Auth's @supabase/ssr package makes Next.js App Router integration smoother once you add server-side checks, which almost every real app eventually needs.

Does Supabase Auth support social login like Google and GitHub?

Yes — Supabase Auth supports Google, GitHub, Apple, Discord, and dozens of other OAuth providers, configured directly from the Supabase dashboard with no extra backend code required.

Is Firebase Auth open source?

No. Firebase Auth is a fully managed Google Cloud service — you can't self-host it or inspect its internals. Supabase Auth (part of the broader Supabase platform, built on the open-source GoTrue project) is open source and can be self-hosted.

Do I need Row Level Security if I'm already checking auth in my Next.js code?

RLS protects your database from application-level mistakes and direct client access, but it does not protect against misuse of a secret/service-role key because those elevated keys bypass RLS.

Wrapping Up

Supabase Auth and Firebase Auth both get you a working login system fast — the real decision comes down to what's underneath: a relational Postgres database with SQL-based security, or Firestore's document model with Google's rules language. If your app has real relationships between users, teams, and data, Supabase's Postgres foundation will save you pain down the road. If you're already deep in the Google Cloud ecosystem, Firebase Auth keeps everything under one roof.

Whichever you pick, remember the same rule applies to both: UI checks are for user experience, and server-side/database-level checks are your actual security boundary.

Continue Learning

Helpful Free Tools

Supabase RLS Policy Generator — generate strict, pattern-specific Row Level Security policies in seconds instead of hand-writing SQL.
Zod Schema Generator — generate validated schemas for your auth forms straight from JSON or TypeScript, including a ready-to-use Server Action.

Role-Based Access Control (RBAC) in Next.js 16 (2026 Beginner's Guide)

Syed Muhammad Ali — Wed, 29 Jul 2026 19:00:00 +0000

Logging a user in is the easy part. The hard part shows up right after — when your "admin" and your "customer" both hit /dashboard and somehow need to see completely different things. Or worse, when a regular user figures out they can just type /admin into the URL bar and… get in, because nothing was actually checking who they were.

That's the gap role-based authorization (RBAC — Role-Based Access Control) fills. It's not about whether someone is logged in anymore — it's about what they're allowed to do once they are. An admin can delete users. An editor can publish posts. A viewer can only look. Same login system, three completely different sets of permissions.

In this guide, you'll build a complete role-based authorization system in Next.js 16 — from storing roles, to protecting routes with proxy.ts, to locking down Server Actions and API routes so a sneaky curl request can't bypass your UI checks. By the end, you'll have a reusable pattern you can drop into any SaaS, dashboard, or internal tool.

Why This Is Tricky

Authentication just answers "who are you?" Authorization answers "what are you allowed to do?" — and that second question has to be checked in every place data or actions are exposed, not just once at the login screen.

The mistake almost everyone makes early on is checking roles only in the UI — hiding an "Edit" button if role !== "admin". That stops confused users, but it does nothing to stop a determined one, since a hidden button doesn't stop someone from calling the underlying Server Action or API route directly. Real role-based auth needs checks in at least three layers:

Route level — don't even let the page load for the wrong role
UI level — hide actions the user can't perform (good UX, not security)
Server level — re-verify inside every Server Action, Route Handler, and database query (the actual security boundary)

We'll build all three.

What We're Building

A small app with three roles:

admin — full access, can manage users
editor — can create and edit posts
viewer — read-only access

You'll end up with:

A typed Role system shared across the whole app
Role storage using Auth.js v5's JWT session (works the same pattern with a database session)
Route protection in proxy.ts based on role, not just login state
A reusable requirePermission() helper for Server Actions and Route Handlers
A <Can> component for conditionally showing UI based on permissions

                 ┌──────────────┐
                 │    Role      │
                 │ admin/editor │
                 │    viewer    │
                 └──────┬───────┘
                        ↓
                 ┌──────────────┐
                 │ Permissions  │
                 └──────┬───────┘
                        ↓
              ┌─────────┴─────────┐
              ↓                   ↓
      requirePermission()       <Can>
              ↓                   ↓
       Security boundary      UI visibility

Tech Stack

This guide uses:

Next.js 16 with the App Router
TypeScript in strict mode
Tailwind CSS for the small UI examples
Auth.js v5 (next-auth@beta) for authentication — the same library covered in Clerk vs NextAuth (Auth.js) in 2026

💡 Tip: Don't have Auth.js set up yet? Read How to Add Auth.js (NextAuth v5) Authentication in Next.js 16 first — this guide picks up right where that one leaves off. If you're using Clerk instead, skip to the Clerk section near the end — the concepts are identical, just the plumbing changes.

Step 1: Define Your Roles in One Place

Before writing any auth code, decide what roles exist and what each one can actually do. Hardcoding role strings ("admin", "editor"...) all over your codebase is exactly how typos slip in and silently break a permission check.

// lib/auth/roles.ts
export const ROLES = ["admin", "editor", "viewer"] as const;

export type Role = (typeof ROLES)[number];

// What each role is allowed to do — the single source of truth
export const PERMISSIONS = {
  admin: ["manage_users", "create_post", "edit_post", "delete_post", "view_post"],
  editor: ["create_post", "edit_post", "view_post"],
  viewer: ["view_post"],
} as const satisfies Record<Role, readonly string[]>;

export type Permission = (typeof PERMISSIONS)[Role][number];

export function hasPermission(role: Role, permission: Permission): boolean {
  return (PERMISSIONS[role] as readonly string[]).includes(permission);
}

What's happening here: ROLES is a fixed list — TypeScript's as const makes Role a union type ("admin" | "editor" | "viewer") instead of a loose string, so a typo like "admn" fails to compile instead of silently failing at runtime. PERMISSIONS maps each role to what it's allowed to do, and hasPermission() is the one function every check in this guide will eventually call.

💡 Tip: Notice we're checking permissions ("create_post"), not roles ("editor"), everywhere except this one file. If you ever add a new role or change what editors can do, you update this file once — nothing else in your app needs to change.

Step 2: Store the Role on the User

Your role has to live somewhere Auth.js can read it during login. In a real app, this is a role column on your users table. For this guide, here's the shape assuming you're using a database adapter (Prisma, Drizzle, or similar):

-- Minimal schema addition
alter table users
add column role text not null default 'viewer'
check (role in ('admin', 'editor', 'viewer'));

New users default to the lowest-privilege role — viewer — which is a good default for any RBAC system. Never default a new signup to admin.

TypeScript protects application code at compile time; the database constraint protects persisted data at runtime.

⚠️ Common Mistake: Letting the client send its own role during signup (formData.get("role")). Always assign the default role server-side and require an existing admin to promote anyone — otherwise anyone can sign up and just declare themselves an admin.

Step 3: Put the Role on the Session

This is the step most tutorials skip, and it's the one that actually makes RBAC work. By default, Auth.js's session only contains the basics (name, email, image) — you have to explicitly add role to it using two callbacks: jwt and session.

// lib/auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import type { Role } from "./auth/roles";

declare module "next-auth" {
  interface User {
    id: string;
    role: Role;
  }
  interface Session {
    user: {
      id: string;
      role: Role;
    } & DefaultSession["user"];
  }
}

declare module "@auth/core/jwt" {
  interface JWT {
    role: Role;
    id: string;
  }
}

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [GitHub],
  callbacks: {
    async jwt({ token, user }) {
      // Runs on sign-in, and on every subsequent request
      if (user) {
        // `user` is only defined right after login — look up the role from your DB here
        token.id = user.id!;
        token.role = user.role ?? "viewer";
      }
      return token;
    },
    async session({ session, token }) {
      // Copies data from the JWT token into the session object your app actually reads
      session.user.id = token.id;
      session.user.role = token.role;
      return session;
    },
  },
});

What's happening here: jwt() can run whenever the JWT session is created or updated, but the user object is available during the initial sign-in flow. That's where you copy the user's role into token.role. On later requests, the role is read from the token rather than fetched again. session() then runs on every auth() call and copies fields from that token onto the session object your pages and Server Actions actually read. The declare module blocks aren't runtime code — they extend Auth.js's built-in TypeScript types so session.user.role autocompletes instead of throwing a type error.

⚠️ Common Mistake: Trying to read the role directly off session.user without adding it in these two callbacks first. Auth.js won't magically know about a custom role column — you have to wire it through jwt() → session() explicitly, every time.

💡 Tip: If a user's role changes (e.g. an admin promotes them), the JWT won't reflect that until they log in again, since jwt() only re-reads user on fresh sign-in. For roles that need to update instantly, either switch to database sessions (strategy: "database") or add a trigger === "update" branch that re-fetches the role on demand.

Step 4: Protect Routes by Role in `proxy.ts`

In Next.js 16, middleware.ts was renamed to proxy.ts — same file conventions, same idea: it runs before a request reaches a page, making it useful for a fast, optimistic route-level redirect before the page renders.

// proxy.ts
import { NextResponse } from "next/server";
import { auth } from "@/lib/auth";
import type { Role } from "@/lib/auth/roles";

// Map route prefixes to the roles allowed to access them
const ROUTE_ROLES: { prefix: string; roles: Role[] }[] = [
  { prefix: "/admin", roles: ["admin"] },
  { prefix: "/editor", roles: ["admin", "editor"] },
  { prefix: "/dashboard", roles: ["admin", "editor", "viewer"] },
];

export default auth((req) => {
  const { nextUrl } = req;
  const role = req.auth?.user?.role;

  const matched = ROUTE_ROLES.find((r) => nextUrl.pathname === r.prefix || nextUrl.pathname.startsWith(`${r.prefix}/`));
  const isAuthPage = nextUrl.pathname === "/login";
  const isLoggedIn = !!req.auth;

  if (isAuthPage && isLoggedIn) {
      // Redirect authenticated users to the dashboard
      return NextResponse.redirect(new URL("/dashboard", nextUrl))
  }

  if (!matched) {
    return NextResponse.next(); // route isn't role-protected, let it through
  }

  if (!isLoggedIn) {
    // Not logged in at all — send to login
    return NextResponse.redirect(new URL("/login", nextUrl));
  }

  if (!role || !matched.roles.includes(role)) {
    // Logged in, but wrong role — send to a friendly "not allowed" page, not login
    return NextResponse.redirect(new URL("/unauthorized", nextUrl));
  }

  return NextResponse.next();
});

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

What's happening here: ROUTE_ROLES is a lookup table — no scattered if statements per route, just prefixes mapped to the roles allowed in. The proxy checks the incoming path against that table, and only bothers checking req.auth at all if the route is actually protected. Notice the two different redirects: no session → /login (they need to authenticate), wrong role → /unauthorized (they're authenticated, just not allowed here) — conflating these two cases is a common source of confusing UX.

⚠️ Common Mistake: Forgetting the matcher config, or matching too broadly. Running the proxy on every static asset request adds unnecessary overhead and can cause odd caching behavior — always exclude _next/static, _next/image, and favicon paths.

Step 5: Build a `requirePermission()` Helper for the Real Security Boundary

proxy.ts stops the page from loading, but it does not protect Server Actions or Route Handlers called directly — those need their own check. This is the layer that actually matters for security, since proxy.ts is a UX nicety, not a guarantee.

// lib/auth/require-role.ts
import { auth } from "@/lib/auth";
import type { Permission } from "./roles";
import { hasPermission } from "./roles";

export class UnauthorizedError extends Error {}
export class ForbiddenError extends Error {}

export async function requirePermission(permission: Permission) {
  const session = await auth();

  if (!session?.user) {
    throw new UnauthorizedError("You must be signed in.");
  }

  if (!hasPermission(session.user.role, permission)) {
    throw new ForbiddenError("You don't have permission to do that.");
  }

  return session.user; // callers get a typed, guaranteed-authorized user back
}

What's happening here: requirePermission() checks permissions ("delete_post"), not roles directly — this keeps every call site decoupled from which roles can do what, so changing that mapping later only touches roles.ts. Two distinct errors (Unauthorized vs Forbidden) let callers respond differently — a 401 (not logged in) is a different problem than a 403 (logged in, not allowed).

Using It in a Server Action

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

import { requirePermission, ForbiddenError, UnauthorizedError } from "@/lib/auth/require-role";
import { revalidatePath } from "next/cache";

export async function deletePost(postId: string) {
  try {
    await requirePermission("delete_post");
  } catch (err) {
    if (err instanceof UnauthorizedError) return { error: "Please sign in." };
    if (err instanceof ForbiddenError) return { error: "You can't delete posts." };
    throw err;
  }

  // await db.post.delete({ where: { id: postId } });
  revalidatePath("/dashboard");
  return { success: true };
}

⚠️ Common Mistake: Only checking permissions in proxy.ts and assuming Server Actions are automatically covered. They aren't — a Server Action is a real network endpoint under the hood, callable directly, and needs its own requirePermission() call every single time it touches something sensitive.

Using It in a Route Handler

// app/api/users/[id]/route.ts
import { NextResponse } from "next/server";
import { requirePermission, ForbiddenError, UnauthorizedError } from "@/lib/auth/require-role";

export async function DELETE(req: Request, { params }: { params: Promise<{ id: string }> }) {
  try {
    await requirePermission("manage_users");
  } catch (err) {
    if (err instanceof UnauthorizedError) {
      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
    }
    if (err instanceof ForbiddenError) {
      return NextResponse.json({ error: "Forbidden" }, { status: 403 });
    }
    throw err;
  }

  const { id } = await params;
  // await db.user.delete({ where: { id } });
  return NextResponse.json({ success: true });
}

Same pattern, correct HTTP status codes this time — 401 for "log in first," 403 for "you're logged in, but no."

Step 6: Conditionally Show UI with a `<Can>` Component

Server-side checks are the real security boundary, but users still need a UI that doesn't dangle buttons they can't actually use. A small <Can> component keeps this readable instead of {role === "admin" && ...} scattered through every page.

// components/can.tsx
import type { Permission } from "@/lib/auth/roles";
import { hasPermission } from "@/lib/auth/roles";
import { auth } from "@/lib/auth";

interface CanProps {
  permission: Permission;
  children: React.ReactNode;
  fallback?: React.ReactNode;
}

export async function Can({ permission, children, fallback = null }: CanProps) {
  const session = await auth();

  if (!session?.user || !hasPermission(session.user.role, permission)) {
    return <>{fallback}</>;
  }

  return <>{children}</>;
}

// app/dashboard/page.tsx
import { Can } from "@/components/can";
import Link from 'next/link';

export default function DashboardPage() {
  return (
    <div className="space-y-4">
      <h1 className="text-2xl font-semibold">Dashboard</h1>

      <Can permission="create_post">
        <button className="rounded-lg bg-primary px-4 py-2 text-white">
          New Post
        </button>
      </Can>

      <Can permission="manage_users" fallback={<p className="text-sm text-muted-foreground">Admins only.</p>}>
        <Link href="/admin/users" className="underline">Manage Users</Link>
      </Can>
    </div>
  );
}

What's happening here: Can is an async Server Component — it calls auth() directly, no client-side loading flicker, no useEffect. Wrap anything role-gated in it, optionally supply a fallback for what non-permitted users see instead (or leave it out to render nothing at all).

💡 Tip: Because Can reads the current session on the server, use it in parts of the tree where request-time authentication data is expected.

💡 Tip: This component controls visibility, not security. Someone could still call the underlying Server Action with dev tools open — that's exactly why Step 5's requirePermission() exists as the real gate. <Can> is UX, requirePermission() is the lock.

Step 7: Filter Data at the Query Level Too

There's a fourth layer worth calling out separately: what data a query even returns. A viewer shouldn't just be blocked from an edit button — if your query returns draft posts by default, make sure a viewer's query never fetches drafts in the first place, rather than fetching everything and hiding it in the UI.

// lib/data/posts.ts
import { auth } from "@/lib/auth";
import { UnauthorizedError } from "../auth/require-role";

export async function getVisiblePosts() {
  const session = await auth();
  const role = session?.user?.role;

  if (!session?.user) {
    throw new UnauthorizedError("You must be signed in.");
  }

  if (role === "admin" || role === "editor") {
    // return await db.post.findMany(); // everything, including drafts
  }

  // return await db.post.findMany({ where: { status: "published" } }); // viewers only see published
}

This matters because a UI-only check can miss cases like server-rendered pages, RSS feeds, or an API response that isn't wired through the component you added <Can> to.

Frequently Asked Questions

What's 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 (roles and permissions). You need both — Auth.js/Clerk handle authentication, and everything in this guide is the authorization layer on top.

Should I store roles as a string or a separate roles table?

A single role string column (like this guide uses) is fine for simple apps with a handful of fixed roles. If you need multiple roles per user, per-organization roles, or roles that admins can create dynamically, move to a proper roles and user_roles join table instead — the hasPermission() pattern still works the same way on top of either.

Is checking roles in `proxy.ts` enough security by itself?

No. Treat proxy.ts as a fast UX redirect, not your security boundary — it can be bypassed by hitting a Server Action or API route directly. Always re-check permissions inside the Server Action or Route Handler itself, as shown in Step 5.

How do I handle a role change without forcing the user to log out?

With JWT sessions, the user value isn't available on every JWT callback invocation, so simply changing the role in your database doesn't automatically replace the role already stored in an existing token. Either switch to strategy: "database" sessions (Auth.js re-reads the DB on every request), or add an update() trigger that refreshes the token when an admin changes someone's role.

Can I have more granular permissions than just three roles?

Yes — that's exactly why Step 1 separates PERMISSIONS from ROLES. Add a new permission string to whichever roles should have it, and every requirePermission() call automatically respects the new mapping without touching the rest of your codebase.

Doing This with Clerk Instead

If you're using Clerk instead of Auth.js, the RBAC architecture stays the same. Only the way you retrieve the user's role changes.

For a simple app, store the role in Clerk's publicMetadata:

{
  role: "editor"
}

Set it server-side or through the Clerk Dashboard. Never let users submit their own role during signup.

Expose the metadata through the Clerk session token. In Clerk Dashboard → Sessions → Customize session token, add:

{
  "metadata": "{{user.public_metadata}}"
}

Then read the role with auth():

import { auth } from "@clerk/nextjs/server";
import type { Role } from "@/lib/auth/roles";

const { isAuthenticated, sessionClaims } = await auth();

if (!isAuthenticated) {
  // Not signed in
}

const role = sessionClaims?.metadata?.role as Role | undefined;

From here, the same hasPermission(), requirePermission(), and <Can> pattern from this guide still applies. Your authorization layer doesn't need to care whether the role came from Auth.js or Clerk.

Role changes may take a short time to appear in an existing session token, so don't assume a metadata update is immediately reflected in sessionClaims.

💡 Tip: If you're building a multi-tenant SaaS with teams or organizations, consider Clerk's built-in Organizations, Roles, and Permissions instead of storing organization roles in publicMetadata. (Clerk Roles & Permissions)

The important rule remains the same: UI checks improve UX; server-side permission checks provide security.

Wrapping Up

Role-based authorization isn't one big feature — it's four small, boring checks layered together: a protected route in proxy.ts, a re-check inside every Server Action and Route Handler, a <Can> wrapper for the UI, and a query that filters data before it ever leaves the server. Skip any one layer and you've got a gap; stack all four and a "hidden" admin button stops being a real vulnerability.

From here, a natural next step is adding an admin UI for promoting/demoting users, or layering row-level security on top if you're using Supabase alongside this pattern for defense in depth at the database layer too.

📦 Source Code: View on GitHub

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.

Google Search Console Setup for Next.js (2026 Beginner's Guide)

Syed Muhammad Ali — Tue, 28 Jul 2026 10:22:27 +0000

You just shipped your Next.js site. Metadata's wired up, Open Graph tags look great, JSON-LD is in place — and yet Google has no idea your site exists. Weeks go by, you check your analytics, and organic traffic is basically zero.

Here's the thing nobody tells beginners: writing good SEO code isn't the same as telling Google to actually crawl it. That connection happens through one tool — Google Search Console (GSC) — and it's one of the most important tools new Next.js developers should set up after launch.

By the end of this guide, you'll have Google Search Console fully connected to your Next.js 16 App Router site, a submitted sitemap, a correctly configured robots.txt, and a repeatable process for catching indexing problems before they cost you traffic.

Why This Is Tricky

Google Search Console isn't part of your codebase, so it's easy to treat it as an afterthought — something you'll "get to later." But GSC is the only place that tells you:

Whether Google can actually crawl your pages
Which pages are indexed (showing up in search) versus silently ignored
Real search queries people used to land on your site
Core Web Vitals issues that can contribute to a poor page experience and potentially affect search performance

Without it, you're optimizing blind. You could have a metadata bug shipping noindex to your entire site for a week and never know until traffic craters.

Prerequisites

This guide assumes:

Next.js 16 with the App Router
TypeScript in strict mode
A site already deployed to a live domain (Vercel, Netlify, or self-hosted — the Next.js side works the same everywhere)
Access to your domain's DNS settings (through your registrar or host)

If your project doesn't have app/sitemap.ts or app/robots.ts yet, don't worry — we'll build both from scratch.

Step 1: Create the Google Search Console Property

Head to search.google.com/search-console and sign in with the Google account you want to permanently own this property. If you're doing this for a client, use an account you control and add them as a verified owner afterward — don't set the property up under their personal Gmail unless you're handing off the project entirely.

You'll be asked to choose a property type:

Property type	Covers	Verification
Domain property	All subdomains and both `http`/`https` versions under one property	DNS only
URL-prefix property	Just the exact URL pattern you enter	DNS, HTML file, meta tag, GA, or GTM

💡 Tip: For a new site, go with a Domain property. It's the most complete option — you get www and non-www, http and https, and every subdomain in a single dashboard instead of juggling separate properties for each variant.

The tradeoff is that Domain properties only support DNS verification, which means you need access to your domain's DNS zone (through your registrar, or through Vercel's domain settings if Vercel manages your DNS).

Step 2: Verify Ownership

Option A — DNS TXT Record (Recommended for Domain Properties)

This is the most reliable method because it's tied to the domain itself, not a specific file or page — it survives redeploys, framework migrations, and hosting changes.

GSC gives you a TXT record value that looks like google-site-verification=abc123...
Log into your DNS provider (Cloudflare, Namecheap, GoDaddy, or your registrar)
Add a new TXT record:
- Host/Name: @ (represents your root domain)
- Value: the code GSC gave you
- TTL: default (usually 3600)
Save, go back to GSC, and click Verify

⚠️ Common Mistake: DNS changes aren't instant. Some providers (Cloudflare especially) propagate in 2–3 minutes, but others can take up to an hour. If verification fails immediately, wait and retry rather than assuming you did something wrong.

Option B — HTML Meta Tag (URL-Prefix Properties)

If you went with a URL-prefix property instead, GSC gives you a meta tag like:

<meta name="google-site-verification" content="your-code-here" />

In Next.js's App Router, don't paste this directly into a <head> tag — the Metadata API has a dedicated field for it:

// app/layout.tsx
import type { Metadata } from "next";

export const metadata: Metadata = {
  // ...your existing metadata
  verification: {
    google: "your-code-here",
  },
};

What's happening here: Next.js's Metadata API generates the correct <meta name="google-site-verification"> tag for you, merged in with the rest of your root layout's metadata. This is safer than hand-editing HTML because it can't accidentally get wiped out by a template change.

⚠️ Common Mistake: Only setting the verification field in a nested page's metadata instead of the root app/layout.tsx. Google checks your homepage for this tag, so it has to live in metadata that actually applies to /.

Redeploy, then click Verify in GSC.

Step 3: Generate a Sitemap with `sitemap.ts`

A sitemap is a map of every URL you want indexed. It doesn't force Google to index anything, but it can make URL discovery more efficient — especially for new sites, large sites, or pages with few internal links.

Next.js has a built-in file convention for this — no packages needed:

// app/sitemap.ts
import { MetadataRoute } from "next";
import { getAllPosts } from "@/lib/posts";
import { appURL } from "@/lib/utils";

export default function sitemap(): MetadataRoute.Sitemap {
  const posts = getAllPosts().map((post) => ({
    url: `${appURL}/blog/${post.slug}`,
    lastModified: new Date(post.updatedAt || post.publishedAt),
  }));

  const staticRoutes = ["", "/about", "/blog", "/contact"].map((route) => ({
    url: `${appURL}${route}`,
  }));

  return [...staticRoutes, ...posts];
}

What's happening here: dropping a file named sitemap.ts inside app/ tells Next.js to automatically generate a working route at /sitemap.xml — you never manually build or serve XML. lastModified tells search engines when a page was last meaningfully updated. Google can use an accurate lastmod value when deciding when to recrawl a URL. Although Next.js supports changeFrequency and priority, Google says it ignores those two sitemap values, so don't treat them as ranking or crawling controls.

💡 Tip: Only include canonical URLs that you actually want search engines to discover and potentially index. Don't add /admin, /api/*, private pages, draft URLs, or other non-indexable routes to your sitemap.

Step 4: Configure `robots.ts` Correctly

robots.txt tells crawlers which URLs they can or can't request. It controls crawling — not whether a page can appear in search results.

// app/robots.ts
import { MetadataRoute } from "next";
import { appURL } from "@/lib/utils";

export default function robots(): MetadataRoute.Robots {
  return {
    rules: {
      userAgent: "*",
      allow: "/",
      disallow: ["/admin", "/api"],
    },
    sitemap: `${appURL}/sitemap.xml`,
  };
}

What's happening here: same pattern as the sitemap — Next.js auto-generates a working /robots.txt from this file. allow: "/" lets crawlers visit everything by default, disallow blocks specific internal paths, and pointing sitemap at your sitemap URL here means crawlers can discover it even before you manually submit it in GSC.

⚠️ Common Mistake: Leaving disallow: "/" in robots.ts after moving from a staging environment to production. This single line blocks your entire site from every search engine. Always double-check this file immediately after your first production deploy.

Tip If you need to prevent a page from being indexed, use noindex rather than relying on robots.txt.

Step 5: Submit Your Sitemap in GSC

Once you're verified:

In the GSC sidebar, click Sitemaps
Enter sitemap.xml (GSC prepends your domain automatically)
Click Submit

You should see a "Success" status within a few minutes, though it can take a day or two before "Discovered URLs" starts populating.

💡 Tip: If your sitemap shows "Couldn't fetch," visit yourdomain.com/sitemap.xml directly in your browser first. If it 404s, the issue is your deployment, not GSC — check that app/sitemap.ts actually made it into your production build.

Step 6: Verify Robots Meta Tags Aren't Blocking Individual Pages

robots.txt controls crawling at the site level, but an individual page can still say "don't index me" through page-level metadata — easy to forget on a page you copy-pasted from a draft.

// app/some-page/page.tsx
import type { Metadata } from "next";

export const metadata: Metadata = {
  robots: {
    index: false,
    follow: false,
  },
};

⚠️ Common Mistake: Setting index: false on the root layout "just to be safe" during development, then forgetting to flip it before launch. This is one of the most common reasons a brand-new Next.js site gets zero organic traffic for weeks — always check your homepage's rendered <meta name="robots"> tag in production before assuming GSC is the problem.

You normally don't need to explicitly set index: true and follow: true. The important thing is making sure you haven't accidentally configured these false on pages you want in search.

You can check this instantly using GSC's URL Inspection Tool (covered next) — it tells you directly whether Google sees a page as indexable.

Step 7: Use URL Inspection to Force Indexing

The URL Inspection Tool is the single most useful feature in GSC day-to-day. Paste any URL from your site into the search bar at the top of GSC, and it tells you:

Whether the page is currently indexed
When it was last crawled
Whether anything (robots meta, canonical mismatch, noindex) is blocking it

After publishing a new page or fixing a metadata bug, you can use Request Indexing to ask Google to recrawl the URL. It doesn't guarantee immediate crawling or indexing, so use your sitemap for ongoing URL discovery rather than repeatedly requesting individual URLs.

💡 Tip: Request Indexing has a daily quota per property. Don't use it for bulk resubmission of your whole site — that's what your sitemap is for. Reserve it for genuinely new or recently fixed pages.

Step 8: Check Core Web Vitals

GSC's Core Web Vitals report shows real-user field data (from actual Chrome visitors), not just a local Lighthouse score. This matters because Core Web Vitals are used by Google's ranking systems, and lab data can look great locally while real users on slower connections or devices have a worse experience.

Watch for pages slipping from "Good" into "Needs improvement" or "Poor" — this is usually caused by:

Unoptimized images (missing next/image, or missing width/height)
Large third-party scripts loaded without next/script strategy
Web fonts causing layout shift instead of using next/font

The report uses real-user data rather than a synthetic Lighthouse test, so your local performance score and your users' actual experience can tell different stories.

Related: Image Optimization in Next.js 16 covers the next/image configuration options that most directly affect this report.

Step 9: Check Your Canonical URLs

Google doesn't only decide whether a page can be indexed — it also chooses which URL represents duplicate or very similar versions of the same content.

In Next.js, make sure important pages have the correct canonical URL, especially if your site supports multiple URL variations.

import type { Metadata } from "next";

export const metadata: Metadata = {
  alternates: {
    canonical: "https://example.com/blog/my-post",
  },
};

⚠️ A canonical URL is a hint, not a guarantee. Google can choose a different canonical if it determines another URL is a better representative of the content.

Step 10: Understanding "Discovered — Currently Not Indexed"

Sooner or later you'll open the Page indexing report and see a bucket of URLs labeled Discovered — currently not indexed. This is one of the most common statuses beginners panic over, so it's worth understanding what it actually means.

It means Google found the URL — usually through your sitemap or an internal link — but hasn't crawled and indexed it yet. This is different from Crawled — currently not indexed, where Google did visit the page but chose not to index it. Both statuses are common and don't always signal a problem; a brand-new site with dozens of freshly submitted URLs will often show a pile of "Discovered" pages that clear up on their own within a couple of weeks.

That said, if a URL sits in this state for more than two to three weeks, it's worth investigating:

Thin or low-value content — tag pages, barely-filled pages, or near-duplicates may provide little unique value. Make sure important URLs contain useful, distinct content.
Crawl budget — very large sites, or sites publishing a lot of near-identical pages quickly, can outpace how much Google is willing to crawl in a given period.
Weak internal linking — a page with no other pages linking to it signals lower importance. Link to new posts from your homepage, a category page, or related content shortly after publishing.
Server response issues — if Googlebot hit a slow response or a temporary error when it tried to crawl, it may deprioritize a retry rather than fail loudly.

💡 Tip: Don't spam Request Indexing on the same "Discovered" URL every day — it doesn't speed anything up and doesn't change why Google deprioritized the crawl in the first place. Fix the underlying content or linking issue, then request indexing once.

Step 11: Don't Forget Bing Webmaster Tools

Google isn't the only crawler worth your time. Bing powers Microsoft's search ecosystem and is also an important source of web search visibility beyond Google — real, easy traffic most developers skip entirely.

Sign up at Bing Webmaster Tools
Submit the exact same sitemap.xml you already built — no separate file needed
Bing lets you import your verified site directly from Google Search Console in a couple of clicks, skipping manual re-verification entirely

A Simple Weekly Routine

Set aside 10–15 minutes a week and check:

Performance report — any unusual drops or spikes in clicks/impressions?
Page indexing report — any pages stuck in "Discovered — currently not indexed" for more than two weeks?
Core Web Vitals — any pages that moved from Good to Needs Improvement?

Catching a regression here in week one is a five-minute fix. Catching it three months later, after it's quietly tanked your rankings, is a much longer recovery.

Troubleshooting Checklist

If something isn't working, work through these in order before assuming it's a GSC bug:

[ ] Verification failing? Wait at least 30–60 minutes after adding a DNS TXT record before retrying — propagation isn't instant.
[ ] Verification meta tag "not found"? View your production page source (not localhost) and confirm the google-site-verification tag is actually in the rendered <head> — check it's set in app/layout.tsx, not a nested page.
[ ] Sitemap "Couldn't fetch"? Visit yourdomain.com/sitemap.xml directly in a browser first. A 404 means a deployment problem, not a GSC problem.
[ ] Sitemap fetches but pages aren't indexed? Check robots.ts isn't disallowing the path, and check the page's own metadata isn't setting robots: { index: false }.
[ ] Whole site missing from search? Check app/robots.ts for an accidental disallow: "/" — this is the single most common self-inflicted outage.
[ ] Pages stuck on "Discovered — currently not indexed"? Give it 2–3 weeks first. If it persists, check for thin content and add internal links pointing to the page.
[ ] Core Web Vitals showing "Poor"? Confirm images use next/image, fonts use next/font, and large third-party scripts use next/script with an appropriate loading strategy.
[ ] Data missing entirely after adding the property? This can be normal for a new property. Google says data collection begins when the property is added, even before verification, but it can take up to a week for data to appear.

Frequently Asked Questions

Do I need a Domain property or URL-prefix property for Next.js?

Domain property, in almost every case — it covers www, non-www, and both protocols under one dashboard. Only use URL-prefix if you specifically need isolated data for a subdomain or can't get DNS access.

How long until I see data in Google Search Console?

Search Console doesn't give you historical performance data from before Google started collecting data for the property. Google says data collection can begin when the property is added, even before ownership verification is completed. In practice, expect the reports to take some time to populate, and don't panic if impressions stay low for the first couple of weeks on a brand-new site.

My sitemap shows "Couldn't fetch." What's wrong?

Almost always a deployment issue, not a GSC issue. Visit yourdomain.com/sitemap.xml directly — if it 404s or shows an error, check that app/sitemap.ts is actually included in your production build and isn't being blocked by robots.ts.

Can I use both a DNS TXT record and a meta tag verification?

Yes. You can maintain multiple verification methods. This can be useful as a backup, although you don't need multiple methods for normal operation. Domain properties use DNS verification, while URL-prefix properties support additional methods such as HTML meta tags.

Does adding a sitemap guarantee my pages get indexed?

No. A sitemap only helps Google discover URLs faster — it doesn't override noindex tags, thin-content penalties, or crawl budget limits. Pages still need to pass Google's own quality bar to actually rank.

Wrapping Up

Google Search Console setup for Next.js comes down to five things that take about 20 minutes total: verify ownership, ship app/sitemap.ts, ship a correctly scoped app/robots.ts, submit the sitemap, and build a weekly habit of checking the Performance and Page Indexing reports. None of it is complicated — it's just easy to skip, and skipping it is exactly why so many well-built Next.js sites sit invisible in search for months after launch.

From here, a natural next step is pairing this with a proper JSON-LD structured data setup so your indexed pages are eligible for rich results, not just a plain blue link.

Continue Learning

Free SEO Tools

JSON-LD Generator for Next.js & HTML - generate Article, FAQ, Product, LocalBusiness, SoftwareApplication, Breadcrumb, Person, Organization, and Website JSON-LD — checked live against Google's actual Rich Results requirements.
Meta Tag Generator for Next.js & HTML — generate SEO meta tags, Open Graph tags, Twitter Cards, and canonical URLs instantly. Handy for wiring up per-post metadata like the generateMetadata() function above.
Supabase RLS Policy Generator — if your next project pairs this blog setup with a Supabase backend, generate secure, performance-optimized Row Level Security policies in seconds.
Zod Schema Generator — generate Zod schemas instantly from JSON or TypeScript. Includes smart inference, live validation, React Hook Form, Next.js API Routes, and Server Actions.

How to Send Newsletters & Bulk Emails with Resend in Next.js 16

Syed Muhammad Ali — Mon, 27 Jul 2026 05:38:41 +0000

If you've ever built a newsletter with Resend, you've probably hit this wall: everything works great for your first handful of subscribers, and then one day you're manually exporting a list from your CMS and pasting emails one by one because your "send to everyone" button either times out, hits a rate limit, or just silently stops partway through.

That's not a you-problem. It's what happens when resend.emails.send() — a function built to send one email to one person — gets asked to do a completely different job: blasting the same content to a list. The good news is Resend actually has purpose-built tools for this, most developers just don't reach for them because the docs default to the single-send example everywhere.

By the end of this guide, you'll know exactly why bulk sends break, which Resend feature to use for which situation, and how to send emails to hundreds (or thousands) of subscribers from Next.js 16 without your route handler timing out or your requests getting rate-limited into oblivion.

💡 Using an older Resend tutorial? Resend recently replaced Audiences with a Segments + Topics model — Contacts are now global (one Contact per email address across your whole account), Segments handle internal list organization, and Topics handle what recipients actually see when they manage their subscription preferences. The audienceId parameter is deprecated. This guide uses the current model throughout; see Resend's migration guide if you have an existing Audiences-based setup to move over.

Why `emails.send()` Stops Working for Newsletters

Three separate problems stack on top of each other the moment you try to "just loop over your users and call resend.emails.send()":

1. Resend rate-limits you. Every team has a request-per-second cap on the API (2–10 requests/sec by default, depending on your account). Fire off 100 send() calls in a tight loop and you'll start getting 429 Too Many Requests responses partway through — which is almost certainly what's been happening to your newsletter.

2. Your server has a time limit. A Next.js Route Handler or Server Action running on Vercel (or most serverless hosts) has a maximum execution time. Even if you avoided the rate limit by adding delays between sends, looping through 100+ emails one at a time can easily blow past that limit — the function gets killed mid-send, and you have no idea who actually got the email.

3. send() isn't the right tool for a list. It's designed for transactional, one-recipient-at-a-time emails — a password reset, a receipt. A newsletter going to your whole subscriber base is a fundamentally different shape of problem, and Resend has features specifically built for it that most tutorials skip.

Once you match the right tool to the job, all three problems mostly disappear on their own.

Which Resend Feature Should You Actually Use?

Before writing any code, pick based on what you're actually sending:

Your situation	Use this
Same newsletter content to your whole subscriber list	Contacts + Segments + Broadcast API
Different content per recipient (e.g. personalized order updates to 50 users)	Batch API
A single transactional email (welcome, password reset)	Plain `emails.send()` — you already have this from the original Resend setup guide

If you're the person who left that comment — resending a newsletter manually from a CMS — you want the first one. Broadcasts exist specifically so you never touch a manual send loop again: Resend's own infrastructure handles the queueing, throttling, and pacing for you.

The New Model in One Minute

Resend's Contacts system changed shape recently, and it affects almost every code sample below, so it's worth understanding upfront:

Contact — a global entity tied to one email address across your entire account. There's no such thing as "the same person in two Audiences" anymore; they're one Contact that can belong to multiple Segments.
Segment — an internal, team-facing way to group Contacts for sending (this is what Audiences used to do). Recipients never see Segment names.
Topic — a recipient-facing subscription category (e.g. "Weekly Newsletter," "Product Updates"). This is what powers the preference page a subscriber sees when they click unsubscribe, letting them opt out of one type of email without unsubscribing from everything.

Resend's own recommendation: use Segments purely for your internal sending organization, and use Topics for anything user-facing around subscribe/unsubscribe. That's the pattern this guide follows.

Prerequisites

This guide assumes:

Next.js 16 with the App Router
TypeScript in strict mode
A Resend account with a recent version of resend and a verified sending domain (covered in the Resend + Next.js 16 setup guide if you haven't done that yet)

npm install resend

// lib/resend.ts
import { Resend } from "resend";

export const resend = new Resend(process.env.RESEND_API_KEY);

Before writing any code, create two things in the Resend dashboard:

A Segment (Audience → Segments → Create Segment) — this is your internal newsletter list.
A Topic (Audience → Topics → Create Topic) — e.g. "Weekly Newsletter" with a default subscription of opt_in — this is what subscribers actually see and manage.

Copy both IDs into .env.local:

RESEND_SEGMENT_ID=seg_xxxxxxxxx
RESEND_NEWSLETTER_TOPIC_ID=top_xxxxxxxxx

Step 1: Stop Storing Subscribers Only in Your CMS

The root cause of "I have to resend manually from my CMS" is usually that your subscriber list lives somewhere Resend doesn't know about. Every send becomes a manual export-and-paste job.

The fix is to sync subscribers into Resend the moment they sign up, instead of only saving them in your CMS or database.

Since a subscribe form lives inside your own app (it's not an external service calling you), a Server Action is the better fit here — no separate API route, no manual fetch, just a function called directly from the form.

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

import { resend } from "@/lib/resend";
import { isValidEmail } from "@/lib/helpers";

const SEGMENT_ID = process.env.RESEND_SEGMENT_ID!;
const NEWSLETTER_TOPIC_ID = process.env.RESEND_NEWSLETTER_TOPIC_ID!;

export async function subscribe(prev: unknown, formData: FormData) {
  const email = formData.get("email") as string;
  const firstName = formData.get("firstName") as string | undefined;

  if (!email || !isValidEmail(email)) {
    return { error: "Please enter a valid email address" };
  }

  const { error } = await resend.contacts.create({
    email,
    firstName,
    unsubscribed: false,
    segments: [{ id: SEGMENT_ID }],
    topics: [{ id: NEWSLETTER_TOPIC_ID, subscription: "opt_in" }],
  });

  if (error) {
    return { error: error.message };
  }

  return { success: true };
}

What's happening here: resend.contacts.create() creates the Contact and, in the same call, adds them to your Segment (internal list) and opts them into your Topic (what they'll see on their preference page). You still keep them in your own database if you want (for account features, etc.), but Resend now has its own copy it can send to, with unsubscribes tracked automatically. Call this from your signup form with useActionState, the same pattern used for the contact form in the original Resend guide.

💡 Tip: You don't need to create Segments or Topics programmatically for a single newsletter — create them once in the dashboard and reuse the IDs. If you do need to create them from code, it's resend.segments.create({ name }) and resend.topics.create({ name, defaultSubscription }).

⚠️ Common Mistake: Only saving subscribers to your own database and never syncing them to Resend. That's exactly what forces the manual CMS export-and-resend workflow — Resend can only send to Contacts it actually knows about.

If you already have an existing list sitting in your CMS or database, migrate it once with a loop against resend.contacts.create() (or a CSV import from the dashboard) — after that, every new signup stays in sync automatically.

Handling Duplicate Contacts

Someone submitting the signup form twice — or re-subscribing after months away — is a when, not an if. Worth knowing upfront so it doesn't surprise you: contacts.create() does not error on a duplicate email. It's easy to assume it would (and it's tempting to write a try/catch around an "already exists" message like the one below), but in practice, calling it again for an address that's already a Contact just succeeds quietly — no error, no second Contact created.

// ⚠️ This looks reasonable but the catch block never actually runs —
// contacts.create() doesn't throw on a duplicate email, it just succeeds.
const { error } = await resend.contacts.create({ email, firstName, segments: [...] });

if (error?.message.toLowerCase().includes("already exists")) {
  // dead code — this condition is never true in practice
}

That's convenient in one sense (you can't accidentally create two Contacts for one email — they're global entities keyed by address, so a second one isn't possible anyway), but it creates a different problem: the response doesn't tell you whether this call just created a brand-new Contact or silently matched an existing one. You can't safely assume a repeat signup refreshed that Contact's name, Segment membership, or Topic subscription — the API gives no signal either way, and relying on undocumented behavior here is asking for a subscriber who resubscribes and doesn't actually get re-added to your Segment.

The robust fix: stop trying to detect the duplicate case at all, and instead always reinforce the Contact's state after create(), regardless of whether it was new or existing. contacts.update(), contacts.segments.add(), and contacts.topics.update() are all safe to call unconditionally — an update on a field that's already correct is a no-op, and adding a Contact to a Segment it's already in doesn't duplicate anything.

There's one wrinkle in the current model worth knowing too: the contacts.update() endpoint only touches first_name, last_name, unsubscribed, and properties — it doesn't accept segments or topics, which is why those need their own calls.

// actions/subscribe.ts (continued)
const { error } = await resend.contacts.create({
  email,
  firstName,
  unsubscribed: false,
  segments: [{ id: SEGMENT_ID }],
  topics: [{ id: NEWSLETTER_TOPIC_ID, subscription: "opt_in" }],
});

if (error) {
  // A genuine failure — bad Segment/Topic ID, auth issue, etc. Not the
  // duplicate case, since that doesn't come back as an error at all.
  return { error: error.message };
}

// Reinforce the Contact's state either way — create() gives no signal
// about whether this address was brand-new or already existed, so don't
// assume its fields/Segment/Topic membership are already correct.
const { error: updateError } = await resend.contacts.update({
  email,
  firstName,
  unsubscribed: false, // treat a re-submission as an explicit re-opt-in
});

if (updateError) {
  return { error: updateError.message };
}

await resend.contacts.segments.add({ email, segmentId: SEGMENT_ID });
await resend.contacts.topics.update({
  email,
  topics: [{ id: NEWSLETTER_TOPIC_ID, subscription: "opt_in" }],
});

return { success: true };

⚠️ Common Mistake: Writing an if (error?.message.includes("already exists")) branch expecting it to handle duplicates. It won't — that branch is unreachable, because contacts.create() doesn't return an error for a duplicate email in the first place. If you want to handle "new vs. existing" differently for some reason (e.g. a different welcome email), you'll need to check your own database for whether you'd already seen that email before calling Resend at all — Resend's response won't tell you.

⚠️ Common Mistake: Blindly setting unsubscribed: false on every update, including ones triggered by something other than the person resubmitting the signup form (e.g. an internal sync job). Only flip someone back to subscribed when the update is actually the result of them opting in again — otherwise you can silently resubscribe someone who deliberately unsubscribed. The same caution applies to setting a Topic's subscription back to opt_in.

Step 2: Send the Newsletter with the Broadcast API

This is the step that replaces "manually resending from my CMS" entirely. A Broadcast is a single email sent to an entire Segment, and Resend's own infrastructure handles pacing the sends against the rate limit — you don't write any batching or delay logic yourself.

This is another case for a Server Action rather than a Route Handler — it's triggered by an admin clicking "Send" inside your own app, not by an external caller, so there's no need for a public API route.

// actions/send-newsletter.ts
"use server";

import { resend } from "@/lib/resend";

const SEGMENT_ID = process.env.RESEND_SEGMENT_ID!;
const NEWSLETTER_TOPIC_ID = process.env.RESEND_NEWSLETTER_TOPIC_ID!;

export async function sendNewsletter(prev: unknown, formData: FormData) {
  const subject = formData.get("subject") as string;
  const html = formData.get("html") as string;

  if (!subject || !html) {
    return { error: "Subject and content are required" };
  }

  const { data: broadcast, error } = await resend.broadcasts.create({
    segmentId: SEGMENT_ID,
    topicId: NEWSLETTER_TOPIC_ID,
    from: "Newsletter <newsletter@yourdomain.com>",
    subject,
    html: `${html}\n\n{{{RESEND_UNSUBSCRIBE_URL}}}`,
    send: true, // create and send in a single call — no separate broadcasts.send() needed
  });

  if (error || !broadcast) {
    return { error: error?.message ?? "Failed to send newsletter" };
  }

  return { success: true, broadcastId: broadcast.id };
}

What's happening here: broadcasts.create() builds the email against your Segment, and passing send: true sends it immediately in the same request — the older two-step create() then broadcasts.send() flow still works if you want to review a draft in the dashboard first, but for a straightforward newsletter this single call is all you need. Resend queues and throttles delivery on their end, respecting Topic opt-outs and global unsubscribes automatically. The action returns almost instantly, because it's just telling Resend "send this" — it isn't the thing looping over 100 recipients itself.

💡 Tip: The {{{RESEND_UNSUBSCRIBE_URL}}} placeholder gets replaced with a working, per-contact unsubscribe/preferences link. Gmail and Yahoo require a working one-click unsubscribe for bulk senders as of their 2024 sender guidelines — don't skip it.

Because this action returns fast and Resend does the heavy lifting asynchronously, this alone solves the timeout problem for a standard newsletter send — there's no long-running loop in your app to time out in the first place.

⚠️ Common Mistake: Setting send: true without realizing there's no undo — a Broadcast sent this way goes out immediately. If you want a review step, drop send: true, call resend.broadcasts.send(broadcast.id) separately once you've previewed it in the dashboard.

Scheduling Broadcasts

If you don't want to hit send manually at all — say you want every newsletter to go out at 9am the next day — pass scheduledAt alongside send: true:

const { data: broadcast, error } = await resend.broadcasts.create({
  segmentId: SEGMENT_ID,
  topicId: NEWSLETTER_TOPIC_ID,
  from: "Newsletter <newsletter@yourdomain.com>",
  subject,
  html: `${html}\n\n{{{RESEND_UNSUBSCRIBE_URL}}}`,
  send: true,
  scheduledAt: "tomorrow at 9am",
});

That single option covers "send tomorrow morning" without any extra infrastructure — Resend holds the broadcast and releases it at the scheduled time.

⚠️ Common Mistake: Passing scheduledAt without send: true. Resend's API requires the two together — scheduledAt on its own is silently ignored on a plain draft-only create() call.

For recurring or CMS-driven sends where you need to decide the content and trigger the call on a schedule (rather than just delaying a single send), a few options handle the triggering side:

Vercel Cron — simplest if you're already on Vercel; define a schedule in vercel.json that hits a Route Handler on a timer.
Trigger.dev — better once your scheduling logic gets more complex (retries, conditional sends, multi-step workflows).
GitHub Actions — a scheduled workflow that calls your app's API on a cron schedule, handy if you don't want another paid service.
Your CMS's own scheduler — if your CMS already supports "publish at" dates, have that trigger a webhook to your app when a newsletter post goes live, and kick off the broadcast from there.

For a single one-off "send this tomorrow morning," the native scheduledAt option above is all you need — reach for the others only once you're automating when new content gets sent, not just delaying a specific send.

Step 3: Bulk Sending Different Content Per Recipient

Broadcasts are for identical content sent to a Segment. If you're sending 80 different emails — say, personalized weekly stats to each user — you're back to needing multiple distinct emails, and that's what the Batch API is for. It sends up to 100 separate emails in a single API call, instead of 100 separate HTTP requests.

// lib/send-bulk-emails.ts
import { resend } from "@/lib/resend";

export interface BulkEmail {
  to: string;
  subject: string;
  html: string;
}

export interface BulkSendResult {
  sent: number;
  failed: number;
  batches: number;
}

const BATCH_SIZE = 100; // Resend's per-call limit

export const sendBulkEmails = async (
  emails: BulkEmail[],
  opts: { idempotencyPrefix?: string; delayMs?: number } = {}
): Promise<BulkSendResult> => {
  const batches: BulkEmail[][] = [];

  for (let i = 0; i < emails.length; i += BATCH_SIZE) {
    batches.push(emails.slice(i, i + BATCH_SIZE));
  }

  const result: BulkSendResult = { sent: 0, failed: 0, batches: batches.length };

  for (let i = 0; i < batches.length; i++) {
    const batch = batches[i];

    const sendOptions = opts.idempotencyPrefix
      ? { idempotencyKey: `${opts.idempotencyPrefix}-batch-${i}` }
      : undefined;

    const { data, error } = await resend.batch.send(
      batch.map((email) => ({
        from: process.env.RESEND_FROM_EMAIL,
        to: email.to,
        subject: email.subject,
        html: email.html,
      })),
      sendOptions
    );

    if (error) {
      console.error("Batch send failed:", error.message);
      result.failed += batch.length;
      continue;
    }

    result.sent += data?.data.length ?? 0;

    // Small pause between batches so consecutive batch calls stay
    // comfortably under the per-second rate limit — see the guide's
    // "Common Mistake" callout about Promise.all() on this same step.
    if (batches.length > 1 && i < batches.length - 1) {
      await new Promise((resolve) => setTimeout(resolve, opts.delayMs ?? 600));
      // The delay is only a simple example. In production, prefer 
      // handling 429 responses and Retry-After/rate-limit headers 
      // rather than relying on a fixed delay.
    }
  }

  return result;
};

What's happening here: BATCH_SIZE = 100 matches Resend's own limit — one batch API call can carry up to 100 individual emails, each with its own to, subject, and html. Splitting into chunks of 100 means a 350-person send becomes 4 API calls instead of 350. The 600ms pause is a simple conservative example for sequential requests. Your actual limit depends on your account, so production code should handle rate-limit responses rather than relying on a fixed delay.

⚠️ Common Mistake: Using Promise.all() to fire every batch at once "for speed." That's exactly what triggers 429 rate-limit errors — batches still count as one request each against your per-second limit, so send them sequentially, not concurrently.

Step 4: Preventing Timeouts on Larger Sends

For a few hundred recipients, the batching above usually finishes well inside a normal request timeout. For genuinely large lists (thousands of emails), you have two solid options:

Option A: Run the send after the response, with `after()`

Next.js's after() API lets you return a response to the caller immediately, while your code keeps running in the background for a bit longer — useful for kicking off a bulk send without making an admin wait on a spinner. It works the same way inside a Server Action as it does in a Route Handler, so this stays a Server Action too — triggered by an admin button inside your app.

// actions/send-personalized-batch.ts
"use server";

import { after } from "next/server";
import { sendBulkEmails } from "@/lib/send-bulk-emails";
import { getAllSubscribers, appendSendLog } from "@/lib/db";

export type SendBatchState = {
  error?: string;
  message?: string;
};

export const sendPersonalizedBatch = async (
  _prev: SendBatchState,
  formData: FormData
): Promise<SendBatchState> => {
  const subjectLine = (formData.get("subjectLine") as string) || "This week's update";

  const subscribers = await getAllSubscribers();

  if (subscribers.length === 0) {
    return { error: "No local subscribers yet — add one on the Subscribe page first." };
  }

  const id = crypto.randomUUID();

  // Fire-and-return: the caller gets an instant response, the actual
  // send keeps running after the response has been flushed.
  after(async () => {
    const result = await sendBulkEmails(
      subscribers.map((s, i) => ({
        to: s.email,
        subject: subjectLine,
        html: renderPersonalizedHtml(s.firstName, subjectLine), // Your function to render HTML
      })),
      { idempotencyPrefix: `personalized-${id}` }
    );
    await appendSendLog({
      kind: "batch",
      detail: `Personalized batch finished: ${result.sent} sent, ${result.failed} failed, ${result.batches} batch(es).`,
    });
  });

  return { message: `Send started for ${subscribers.length} local subscriber(s).` };
};

What's happening here: after() schedules the callback to run once the response has been sent, but the platform keeps the function alive long enough to finish it — so the admin triggering the send gets an instant "started" response instead of waiting on hundreds of emails to go out synchronously.

⚠️ Common Mistake: Assuming after() gives you unlimited extra time. It still runs within your platform's function execution ceiling — it just moves the work after the response is sent, it doesn't remove the ceiling entirely. For truly large lists, see Option B.

Option B: Offload to a real queue for very large lists

Once you're sending to thousands of people reliably and repeatedly, reach for a dedicated queue like Upstash QStash or Trigger.dev instead of doing it inline at all. You publish one message per batch (or per recipient), the queue calls your endpoint back with automatic retries, rate-limit-aware pacing, and delivery guarantees — so a mid-send crash or a Vercel redeploy can't silently lose part of your list the way a bare loop can.

Kicking off the enqueue is still admin-triggered from inside your app, so it can be a Server Action. The endpoint QStash calls back to, however, is a different story — that request comes from an external service hitting a public URL, which is exactly what Route Handlers exist for, not Server Actions (which have no callable URL of their own).

// actions/enqueue-newsletter.ts
"use server";

import { Client } from "@upstash/qstash";
import { getAllSubscribers } from "@/lib/db";

export type EnqueueState = {
  error?: string;
  message?: string;
};

const BATCH_SIZE = 100;
const qstashToken = process.env.QSTASH_TOKEN!;
export const enqueueNewsletter = async (
  _prev: EnqueueState,
  formData: FormData
): Promise<EnqueueState> => {
  if (!qstashToken) {
    return {
      error:
        "QSTASH_TOKEN is not set. This step is optional — most newsletters don't need a queue. " +
        "Set it in .env.local if you want to test QStash locally (requires a public URL via ngrok/tunnel for the callback).",
    };
  }

  const subjectLine = (formData.get("subjectLine") as string) || "Queued update";
  const subscribers = await getAllSubscribers();

  if (subscribers.length === 0) {
    return { error: "No local subscribers yet — add one on the Subscribe page first." };
  }

  const batches: { to: string; subject: string; html: string }[][] = [];
  for (let i = 0; i < subscribers.length; i += BATCH_SIZE) {
    batches.push(
      subscribers.slice(i, i + BATCH_SIZE).map((s) => ({
        to: s.email,
        subject: subjectLine,
        html: `<p>Hi ${s.firstName || "there"}, ${subjectLine}</p>`,
      }))
    );
  }

  const qstash = new Client({ token: qstashToken, baseUrl: process.env.QSTASH_BASE_URL });
  const newsletterId = crypto.randomUUID();

  for (const [i, batch] of batches.entries()) {
    await qstash.publishJSON({
      url: `${process.env.NEXT_PUBLIC_APP_URL}/api/newsletter/send-batch-worker`,
      body: { batch, newsletterId, batchIndex: i },
    });
  }

  return { message: `Queued ${batches.length} batch(es) via QStash.` };
};

// app/api/newsletter/send-batch-worker/route.ts
// Route Handler on purpose — QStash calls this URL directly, from outside
// this app. Server Actions have no callable URL, so this piece has to stay
// a Route Handler even though everything else in the guide is an action.
import { NextResponse } from "next/server";
import { sendBulkEmails, type BulkEmail } from "@/lib/send-bulk-emails";

export const POST = async (request: Request) => {
  const body: unknown = await request.json();

  if (
    typeof body !== "object" ||
    body === null ||
    !("batch" in body) ||
    !Array.isArray((body as { batch: unknown }).batch)
  ) {
    return NextResponse.json({ error: "Invalid payload" }, { status: 400 });
  }

  const { batch, newsletterId, batchIndex } = (body as { batch: BulkEmail[]; newsletterId: string; batchIndex: string; });
  const result = await sendBulkEmails(batch, { idempotencyPrefix: `newsletter-${newsletterId}-${batchIndex}` });

  const success = result.failed === 0;
  return NextResponse.json({ received: success, result }, { status: success ? 200 : 500 });
};

This is more infrastructure than most newsletters need — for a straightforward list, Step 2's Broadcast API already solves the problem without a queue. Reach for QStash only once you're past a few thousand recipients or need guaranteed retries on failure.

Broadcast vs. Batch vs. Queue: Quick Comparison

	Broadcast API	Batch API	Batch API + Queue (QStash)
Best for	Identical newsletter content to a whole Segment	Different content per recipient, small–medium lists	Different content per recipient, thousands+
Recipients per call	Entire Segment	Up to 100	Up to 100 per queued batch
Handles pacing for you	Yes — Resend's own infrastructure	No — you chunk and delay manually	Yes — the queue paces callbacks
Retries on failure	Handled by Resend	Manual (idempotency keys)	Automatic, built into the queue
Native scheduling	Yes (`scheduledAt` + `send: true`)	No	Yes (via the queue's own scheduling)
Setup complexity	Low	Low–Medium	Medium–High
Trigger from	Server Action	Server Action / `after()`	Server Action (enqueue) + Route Handler (callback)

Step 5: Avoid Duplicate Sends on Retry

If a batch call fails partway through and you retry it, you don't want to double-email anyone who already received it. Pass an idempotency key so Resend recognizes a retried request and returns the original result instead of sending again.

await resend.batch.send(emailPayload, {
  idempotencyKey: `newsletter-${newsletterId}-batch-${batchIndex}`,
});

What's happening here: as long as the same key is reused for a retry of that exact batch, Resend treats it as the same request rather than a new send — so a network blip on your end doesn't turn into duplicate inboxes for your subscribers.

Step 6: Track Bounces and Complaints with Webhooks

A healthy sender reputation depends on removing bad addresses, not just sending and hoping. Set up a webhook endpoint so Resend tells you when something goes wrong with a specific email.

This one has to stay a Route Handler no matter what — Resend's servers are the ones calling it, so it needs a real, public URL.

// app/api/webhooks/resend/route.ts
// Route Handler on purpose — Resend's servers call this URL directly, so it
// needs a real, public URL. This can't be a Server Action.
import { NextRequest, NextResponse } from "next/server";
import { resend } from "@/lib/resend";
import { markEmailBounced, unsubscribeContact } from "@/lib/db";
import type { WebhookEventPayload } from "resend";

export const POST = async (req: NextRequest) => {
  const payload = await req.text(); // must be the raw body — signature check needs it exactly as sent

  let event: WebhookEventPayload;
  try {
    event = resend.webhooks.verify({
      payload,
      headers: {
        id: req.headers.get("svix-id") ?? "",
        timestamp: req.headers.get("svix-timestamp") ?? "",
        signature: req.headers.get("svix-signature") ?? "",
      },
      webhookSecret: process.env.RESEND_WEBHOOK_SECRET,
    });
  } catch {
    return new NextResponse("Invalid webhook signature", { status: 400 });
  }

  switch (event.type) {
    case "email.bounced": {
      for (const to of event.data.to) await markEmailBounced(to);
      break;
    }
    case "email.complained": {
      // Recipient marked it as spam — unsubscribe them immediately
      for (const to of event.data.to) await unsubscribeContact(to);
      break;
    }
    default:
      break;
  }

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

What's happening here: resend.webhooks.verify() checks the svix-* headers Resend attaches to every webhook request against your RESEND_WEBHOOK_SECRET, throwing if the signature doesn't match. That's what proves the request actually came from Resend and not from someone who found your webhook URL and is spoofing bounce events to unsubscribe your whole list. Register the URL under Webhooks in your Resend dashboard to get the secret and start receiving events.

Bounced or complained-about addresses should stop receiving future sends — repeatedly emailing dead or complaining addresses is one of the fastest ways to tank deliverability for your whole domain.

⚠️ Common Mistake: Calling req.json() before verifying. The signature is computed against the exact raw body Resend sent — parsing it first and re-serializing breaks the check. Always read with req.text(), same as with Stripe webhooks.

💡 For the full breakdown of the signature algorithm and manual verification without the SDK helper, see Resend's own webhook verification docs.

A Quick Pre-Send Checklist

[ ] A Segment exists for internal sending, and a Topic exists for the recipient-facing subscription preference
[ ] Subscribers are synced into Resend as Contacts, not just kept in your own database
[ ] Every signup reinforces state with contacts.update() + contacts.segments.add() + contacts.topics.update(), rather than trying to catch an "already exists" error that never comes
[ ] Newsletter content goes through broadcasts.create({ segmentId, topicId, send: true }), not a manual loop
[ ] Recurring or future-dated sends use scheduledAt with send: true (or a scheduler triggering the action) instead of you remembering to click send
[ ] Personalized bulk sends use resend.batch.send() in chunks of 100, sent sequentially
[ ] Long-running sends are kicked off with after() or a real queue, not run synchronously in the request
[ ] Idempotency keys are set on batch sends you might retry
[ ] Subscribe and send actions are Server Actions; only the webhook and any queue callback stay as Route Handlers
[ ] The webhook endpoint verifies the signature with resend.webhooks.verify() before trusting the payload
[ ] Domain has SPF, DKIM, and DMARC configured (see the Resend setup guide if not)

Frequently Asked Questions

Do I still need `resend.emails.send()` for anything?

Yes — keep using it for one-off transactional emails like password resets or order confirmations. Broadcasts and the Batch API are specifically for sending to multiple people at once; a single transactional email doesn't need either.

What happened to Audiences?

Resend replaced Audiences with a Segments + Topics model. Contacts used to be scoped to one Audience each; now every Contact is a single global entity per email address that can belong to multiple Segments (internal organization) and Topics (recipient-facing subscription preferences). The audienceId parameter on Contacts and Broadcasts is deprecated in favor of segments/segmentId — see Resend's migration guide if you're moving an existing project over.

How many subscribers can a Broadcast actually handle?

Resend's Broadcast infrastructure is built to scale with your Segment size — you're not limited to 100 the way you are with a single Batch API call. It handles the internal pacing against rate limits for you, which is exactly the problem this guide is solving.

What's the real difference between Batch and Broadcast?

Batch sends up to 100 different emails (different recipients, potentially different content) in one API call — you're still the one deciding what goes to whom. Broadcast sends one email to an entire Segment and manages delivery pacing itself. Use Batch for personalized bulk sends, Broadcast for newsletters.

Will my subscribers get duplicate emails if something fails halfway through?

Not if you're using idempotency keys on retried batch calls, and not with Broadcasts at all, since Resend's own infrastructure owns the send rather than your code retrying a loop. This is the exact failure mode manual CMS resending runs into — no idempotency, so a partial failure often means re-sending to people who already got it.

Do I need a database of my own if I'm using Resend Contacts?

Not strictly, but it's still a good idea to keep your own record of subscribers for anything beyond email — account linking, analytics, exporting. Just make sure every subscriber that exists in your database also gets synced to Resend, or you're back to the manual-export problem this guide fixes.

What happens if someone subscribes twice?

Resend Contacts are global entities keyed by email, so you can't end up with two Contacts for the same address — but contacts.create() won't error on a duplicate either, it just succeeds silently without telling you whether it created or matched an existing Contact. Don't write an "already exists" error branch expecting it to catch this case; it won't fire. Instead, always follow create() with contacts.update() + contacts.segments.add() + contacts.topics.update(), which is what Step 1's code does — those calls are safe to run unconditionally on every signup, new or repeat.

Can I schedule a newsletter to go out tomorrow morning?

Yes — pass send: true and scheduledAt: "tomorrow at 9am" (or any natural-language time) to broadcasts.create() and Resend holds it until then. You don't need Vercel Cron, Trigger.dev, or any external scheduler for a single scheduled send; those tools are for automating when the send gets triggered in the first place, like a recurring weekly newsletter tied to your CMS's publish schedule.

Why are some endpoints Server Actions and others Route Handlers?

Server Actions are for code triggered from inside your own app — a signup form, an admin's "send" button. Route Handlers are for anything an external service needs to call over a real URL — Resend's bounce/complaint webhooks, or a queue like QStash calling back into your app. If nothing outside your app needs to hit it directly, a Server Action is simpler; if something external does, it has to be a Route Handler.

Should I use Broadcast or Batch for newsletters?

Almost always Broadcast. Only use Batch if every recipient receives different content.

Wrapping Up

The "resending manually from my CMS" problem almost always comes down to one thing: treating a list-send like a loop of single sends instead of reaching for the tools Resend built specifically for it. Sync subscribers into a Segment the moment they sign up, send newsletters through the Broadcast API instead of a manual loop, and fall back to the chunked Batch API only when every recipient genuinely needs different content.

From here, a natural next step is wiring up the webhook-based bounce handling so your list stays clean automatically, or building out a proper Topics-based preference page so subscribers can pick exactly what they want to hear from you.

📦 Source Code: View on GitHub

Continue Learning

Route Handlers Explained in Next.js 16 (Beginner's Guide)

Syed Muhammad Ali — Fri, 24 Jul 2026 04:57:56 +0000

You've built pages, you've built layouts, and now you need something that isn't a page at all — a webhook endpoint for Stripe, a JSON API for a mobile app, or a route that generates a CSV file on demand. None of that fits inside a page.tsx. That's exactly the gap Route Handlers fill in the Next.js App Router.

If you've used the old Pages Router, Route Handlers are the direct replacement for pages/api. If you're coming from Express or another Node framework, think of them as your app.get() and app.post() — just organized by folder structure instead of a router file.

By the end of this guide, you'll know exactly how Route Handlers work in Next.js 16, how they're different from Server Actions, how caching behaves with the new Cache Components model, and how to build a real, typed API endpoint — including handling dynamic routes and webhooks.

Here's the whole picture at a glance before we dive in step by step:

What Are Route Handlers, Exactly?

A Route Handler is a function that runs on the server and responds to an HTTP request — no HTML, no React, just data. You define one inside a special file named route.ts, and it can live anywhere inside your app directory.

// app/api/hello/route.ts
export async function GET() {
  return Response.json({ message: "Hello from Next.js 16!" })
}

Visit /api/hello in your browser, and you'll get back that JSON — no page rendered, just a raw HTTP response.

💡 Tip: Route Handlers use the standard Web Request and Response APIs — the same ones built into browsers and modern JavaScript runtimes — not the old Express-style req/res objects. That means the skills you learn here also apply outside Next.js.

Why This Is Tricky (For Beginners)

New Next.js developers usually hit two points of confusion:

"Isn't this just an API Route?" — Sort of, but Route Handlers live in app/ and use a completely different file convention (route.ts instead of pulling from pages/api).
"Should I use a Route Handler or a Server Action?" — Both let you run server-side code, but they solve different problems, and picking the wrong one leads to unnecessary complexity later.

Let's clear both of those up before touching any code.

Route Handlers vs. Pages Router API Routes

If you're migrating from the Pages Router, pages/api/hello.ts becomes app/api/hello/route.ts. The concept is identical — a folder-based endpoint — but the syntax changes from a single default export to named exports per HTTP method.

Good to know: You never need to mix API Routes and Route Handlers in the same project. If your project uses the app directory, Route Handlers are your only option for API-style endpoints — the Pages Router pattern doesn't apply anymore.

Route Handlers vs. Server Actions

This is the question that trips up almost everyone, so here's the short version:

	Route Handlers	Server Actions
Called from	Anywhere (browser, mobile app, another server, `curl`)	Only from inside your own React components
Best for	Public APIs, webhooks, third-party integrations	Form submissions, internal data mutations
HTTP control	Full — you choose methods, headers, status codes	Handled for you automatically
URL	Has a real, callable URL	No public URL of its own

Rule of thumb: if something outside your Next.js app (a webhook from Stripe, a mobile client, a public API consumer) needs to call this code, use a Route Handler. If it's a form or button inside your own app calling a server function, a Server Action is simpler and does less boilerplate for you.

Prerequisites

This guide uses:

Next.js 16 with the App Router
TypeScript in strict mode
React Compiler enabled (not directly relevant to Route Handlers, but assumed as the project default)

You don't need any extra packages — everything here ships with Next.js out of the box.

Step 1: The `route.ts` File Convention

A Route Handler is created by adding a route.ts (or route.js) file inside any folder in app/. The folder path becomes the URL.

app/
└── api/
    └── hello/
        └── route.ts       → /api/hello

// app/api/hello/route.ts
export async function GET(request: Request) {
  return Response.json({ message: "Hello, world!" })
}

What's happening here: exporting a function named GET tells Next.js "handle GET requests to this route with this function." The function receives the standard Web Request object and must return a Response (or NextResponse, which extends it).

⚠️ Common Mistake: A route.ts file cannot live in the same folder as a page.tsx at the same segment. app/page.tsx and app/route.ts together will throw a build error — Next.js doesn't know whether that URL should render a page or run an API handler. Nest your Route Handler under a different segment, like app/api/..., instead.

Step 2: Supported HTTP Methods

Route Handlers support the standard HTTP verbs as named exports in the same file: GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS.

// app/api/todos/route.ts
export async function GET() {
  const todos = await getTodosFromDb()
  return Response.json(todos)
}

export async function POST(request: Request) {
  const body = await request.json()
  const newTodo = await createTodo(body)
  return Response.json(newTodo, { status: 201 })
}

What's happening here: one file now handles two different behaviors depending on the incoming HTTP method — a GET request lists todos, a POST request creates one. If a client sends a method you haven't exported (like DELETE on a file with only GET/POST), Next.js automatically responds with a 405 Method Not Allowed — you don't need to handle that yourself.

💡 Tip: Next.js also auto-implements a sensible OPTIONS response for you if you don't define one, which is useful for CORS preflight requests (more on that below).

Response vs. NextResponse, Request vs. NextRequest

Before going further, it's worth clearing up which object to reach for — they show up interchangeably in examples online, which confuses a lot of beginners.

Request / Response — the plain Web APIs, built into the JavaScript runtime itself, not Next.js-specific. Use these when you don't need anything extra — a simple JSON response, or reading a body with request.json().
NextRequest (from next/server) — extends Request with Next.js-only conveniences, most notably request.nextUrl (an already-parsed URL object) and request.cookies. Reach for this the moment you need query params or cookies without manually parsing the URL string.
NextResponse (from next/server) — extends Response with helpers like NextResponse.redirect(), NextResponse.rewrite(), and easier cookie-setting via response.cookies.set(). Use this when you need to redirect, rewrite, or set cookies on the way out.

💡 Tip: A good default: start with plain Request/Response.json() for simple handlers, and upgrade to NextRequest/NextResponse only when you actually need one of their extra features. Both pairs are fully interoperable — a function typed to accept NextRequest still works fine if you never end up using the extra methods.

Step 3: Reading Data From the Request

Most real endpoints need to read something — a JSON body, a query parameter, or a header.

// app/api/search/route.ts
import { NextRequest } from "next/server"

export async function GET(request: NextRequest) {
  // Reading a query param: /api/search?q=nextjs
  const query = request.nextUrl.searchParams.get("q")

  if (!query) {
    return Response.json({ error: "Missing 'q' parameter" }, { status: 400 })
  }

  const results = await searchDatabase(query)
  return Response.json(results)
}

What's happening here: NextRequest (imported from next/server) extends the standard Request with convenience helpers — request.nextUrl gives you an already-parsed URL object, so searchParams.get("q") is easier than manually parsing request.url with the native URL class.

For a JSON body on a POST or PUT request, use request.json():

// app/api/contact/route.ts
export async function POST(request: Request) {
  const { email, message } = await request.json()

  if (!email || !message) {
    return Response.json(
      { error: "Email and message are required" },
      { status: 400 }
    )
  }

  await sendContactEmail({ email, message })
  return Response.json({ success: true })
}

⚠️ Common Mistake: Never trust that email and message exist just because your frontend form requires them. Anyone can send a raw POST request straight to /api/contact with curl, skipping your form entirely — always validate on the server, ideally with a schema library like Zod.

Step 4: Dynamic Route Segments

Just like pages, Route Handlers support dynamic segments using square brackets.

app/
└── users/
    └── [id]/
        └── route.ts        → /users/123, /users/456, etc.

In Next.js 16, the recommended way to type the dynamic segment is the built-in RouteContext helper — it's generated automatically for you based on your actual route structure.

// app/users/[id]/route.ts
import type { NextRequest } from "next/server"

export async function GET(
  request: NextRequest,
  ctx: RouteContext<"/users/[id]">
) {
  const { id } = await ctx.params
  const user = await getUserById(id)

  if (!user) {
    return Response.json({ error: "User not found" }, { status: 404 })
  }

  return Response.json(user)
}

What's happening here: ctx.params is a Promise — this matches the same async params convention used in page.tsx files throughout Next.js 16, so you must await it before reading id. RouteContext<"/users/[id]"> gives you full type-safety without manually writing an interface for every dynamic route.

Good to know: These types are generated when you run next dev, next build, or next typegen — if your editor shows a type error right after creating a new dynamic route, running one of those commands usually fixes it.

Step 5: Caching Behavior

This trips up a lot of people coming from the Pages Router, where API Routes were never cached. In the App Router, it's a little more nuanced.

The short version: Route Handlers are not cached by default. Only GET handlers can opt into caching — every other method (POST, PUT, DELETE, etc.) is always dynamic, even if you configure caching in the same file.

To force a GET handler to be cached as static:

// app/items/route.ts
export const dynamic = "force-static"

export async function GET() {
  const res = await fetch("https://data.example.com/items")
  const data = await res.json()
  return Response.json({ data })
}

If You're Using Cache Components (`"use cache"`)

If your project has Cache Components enabled, GET Route Handlers behave exactly like a normal page: they run dynamically by default, but can be pre-rendered at build time if they don't touch anything request-specific.

// app/api/project-info/route.ts
// No dynamic data — this gets pre-rendered at build time
export async function GET() {
  return Response.json({ projectName: "DevStacked" })
}

// app/api/user-agent/route.ts
import { headers } from "next/headers"

// Reads a request-specific header — this forces the route to run per-request
export async function GET() {
  const headersList = await headers()
  const userAgent = headersList.get("user-agent")
  return Response.json({ userAgent })
}

If you need to mix cached data with per-request logic, pull the cached part into its own function using "use cache" — you can't put "use cache" directly inside the Route Handler body itself.

// app/api/products/route.ts
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 await db.query("SELECT * FROM products")
}

💡 Tip: Prerendering for a GET handler stops the moment it touches anything non-deterministic — a database call without "use cache", Math.random(), or runtime APIs like cookies() and headers(). If a route you expected to be static is showing up dynamic in your build output, one of these is almost always why.

A Quick Word on the Edge Runtime

By default, Route Handlers run on the Node.js runtime — the full Node environment, with access to everything you'd expect (the fs module, native npm packages, longer execution limits). You can opt a specific route into the lighter-weight Edge Runtime instead:

// app/api/geo/route.ts
export const runtime = "edge"

export async function GET() {
  return Response.json({ message: "Running on the Edge" })
}

The Edge Runtime starts faster and runs closer to the user geographically, but it's a stripped-down environment — no fs, no full Node API surface, and not every npm package supports it. Reach for it for small, latency-sensitive handlers (geolocation checks, lightweight redirects); stick with the Node.js default for anything doing real database work, file access, or using Node-only packages like the Stripe or AWS SDKs.

Step 6: Handling Webhooks (Raw Body Access)

Webhooks — like Stripe payment confirmations — are one of the most common real-world uses for Route Handlers. The key detail: webhook signature verification needs the raw, unparsed request body, not JSON.

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

const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET!

export async function POST(req: Request) {
  const payload = await req.text() // raw text, NOT req.json()
  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 })
  }

  // event is now verified — safe to trust
  return NextResponse.json({ received: true })
}

What's happening here: req.text() reads the body exactly as Stripe sent it. If you call req.json() first, the body gets re-serialized slightly differently, and the cryptographic signature check fails — a classic gotcha that has nothing to do with your actual secret key.

Step 7: Adding CORS Support

If your Route Handler needs to be called from a different domain (a separate frontend, a browser extension, another app), you need to explicitly allow it with CORS headers.

// app/api/public-data/route.ts
export async function GET() {
  return Response.json(
    { data: "available to any origin" },
    {
      headers: {
        "Access-Control-Allow-Origin": "*",
      },
    }
  )
}

export async function OPTIONS() {
  return new Response(null, {
    status: 204,
    headers: {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
      "Access-Control-Allow-Headers": "Content-Type, Authorization",
    },
  })
}

⚠️ Common Mistake: Setting CORS headers on GET/POST but forgetting OPTIONS. Browsers send a "preflight" OPTIONS request before certain cross-origin requests, and if that preflight doesn't return the right headers, the browser blocks the real request before it's ever sent — even if your GET handler would have worked fine.

If you need CORS applied consistently across many routes at once, handling it in proxy.ts (formerly middleware.ts) instead of repeating this in every file is usually cleaner.

Route Resolution Rules to Know

A few quick rules worth keeping in mind as your API grows:

A route.ts file cannot exist at the same segment as a page.tsx — pick one per route.
Route Handlers do not participate in layouts or client-side navigation the way pages do. They're the lowest-level routing primitive — pure request in, response out.
Each route.ts takes over every HTTP verb for that exact segment. A nested dynamic segment like app/[user]/page.tsx next to app/api/route.ts is perfectly valid, since they're different paths.

Page	Route	Result
`app/page.tsx`	`app/route.ts`	✗ Conflict
`app/page.tsx`	`app/api/route.ts`	✓ Valid
`app/[user]/page.tsx`	`app/api/route.ts`	✓ Valid

Frequently Asked Questions

Can I use Route Handlers with the Pages Router?

No — Route Handlers only work inside the app directory. If your project still uses pages/, you'd build API endpoints with the older pages/api convention instead, which behaves differently (Express-style req/res rather than Web Request/Response).

Do I need Route Handlers if I'm already using Server Actions?

Not necessarily — plenty of apps only use Server Actions for internal mutations. Reach for a Route Handler specifically when something outside your React component tree needs a callable URL: a webhook, a public API, or a request from a non-Next.js client like a mobile app.

Why isn't my GET Route Handler getting cached?

Route Handlers are dynamic by default. You need to explicitly opt in with export const dynamic = "force-static", or — if you're on Cache Components — make sure the handler doesn't touch runtime APIs like cookies(), headers(), or an uncached database call.

Can I return something other than JSON?

Yes. Response and NextResponse can return any body type — plain text, HTML, a file buffer, even a streamed response. Just set the appropriate Content-Type header so the client knows how to interpret it.

How do I protect a Route Handler so only logged-in users can call it?

Check the session inside the handler itself, the same way you would inside a Server Action — never rely on proxy.ts/middleware alone as your only line of defense. Most auth libraries (Clerk, Auth.js) expose a server-side helper you can call at the top of your GET/POST function to verify the request before doing any real work.

💡 If you haven't set up auth yet, see our guides on Clerk or Auth.js (NextAuth) for the full setup.

Wrapping Up

Route Handlers are the App Router's answer to "I need a real, callable HTTP endpoint" — whether that's a public API, a Stripe webhook, or a small internal utility route. The mental model is simple once it clicks: a route.ts file, named exports per HTTP method, and the standard Request/Response APIs doing the actual work. Layer in dynamic segments, caching with "use cache", and CORS headers as your API grows, and you've got everything you need to build a production-ready backend without leaving your Next.js project.

From here, a natural next step is pairing your Route Handlers with Zod validation for safer request parsing, or wiring one up as a real webhook receiver following the Stripe pattern above.

DEV Community: Syed Muhammad Ali

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

The Quick Answer

Why This Split Exists

Server Components: The Default

What Server Components Are Good At

What Server Components Can't Do

Client Components: Opting Into the Browser

What Client Components Are Good At

How They Actually Work Together

Rule 1: Server Components Can Import Client Components

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

Rule 3: The Fix — Pass Server Components as children

Passing Data Between Server and Client Components

Passing Functions: Server Actions Are the Exception

Common Mistakes to Avoid

A Practical Example: Product Page With a Cart Button

Frequently Asked Questions

Do Server Components run on every request?

Can I use useContext inside a Server Component?

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

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

Should layouts be Server or Client Components?

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

Wrapping Up

Continue Learning

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

Why This Is Tricky

Prerequisites

How Sessions Work

How JWTs Work

Step 1: Set Up the Shared Pieces

Step 2: Build JWT-Based Auth with jose

Create the sign/verify helpers

Create the session cookie on login

Verify the session with a Data Access Layer

Add an optimistic check in proxy.ts

Step 3: Build Database-Backed Sessions

Create the sessions table

Create the session on login

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

Revoking a session — the whole point of this approach

Session vs JWT: Side-by-Side

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

Sliding (Rolling) Sessions

Can You Get Revocation With JWTs?

Which One Should You Actually Use?

Frequently Asked Questions

Can I combine both approaches?

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

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

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

Which one does Auth.js use by default?

Wrapping Up

Continue Learning

Useful Resources

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

Why This Is Confusing

What Is llms.txt, Exactly?

The Required Format

The Companion Idea: .md Versions of Your Pages

llms.txt vs robots.txt vs sitemap.xml

Does Anyone Actually Read It? (The Honest Answer)

Should Your Next.js Site Have One?

When You Probably Don't Need One

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

Step 1: Decide Static or Dynamic

Step 2: Create a Route Handler for /llms.txt

Step 3: Verify the Output

Step 4: Link to It From robots.txt (Optional, but Tidy)

Step 5: Keep It Curated, Not Comprehensive

Frequently Asked Questions

Does llms.txt help my Google rankings?

Is llms.txt an official web standard?

Will ChatGPT or Perplexity actually read my llms.txt?

Should I generate llms.txt dynamically or just write it by hand?

Can llms.txt block AI crawlers from my content?

Wrapping Up

Continue Learning

Free SEO Tools

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

Can I use `useContext` inside a Server Component?

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

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

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

Add an optimistic check in `proxy.ts`

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

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

Step 2: Create a Route Handler for `/llms.txt`

Caching Feature Flag Reads with `next/cache`

Step 1: Catch Rendering Errors with `error.tsx`

Step 2: Handle Root Layout Errors with `global-error.tsx`

`not-found.tsx` for a Specific Segment

`global-not-found.tsx` for Unmatched URLs (New in Next.js 16)

Does `error.tsx` catch errors in event handlers, like an `onClick`?

Can `error.tsx` be a Server Component?

What's the actual difference between `error.tsx` and `not-found.tsx`?

Do I need `global-error.tsx` if I already have `error.tsx` everywhere?

Should I use Sentry or a similar tool instead of just `console.error`?