DEV Community: Shubhra Pokhariya

I Turned On Cache Components in Next.js 16.3. It Refused to Build My Simplest Page.

Shubhra Pokhariya — Wed, 19 Aug 2026 13:58:25 +0000

I didn't want to write another "what's new in Next.js 16.3" post. Enough of those exist. I wanted to know what actually happens when you flip the flags on a real project, so I scaffolded a fresh app, turned on cacheComponents and partialPrefetching, and tried to build the simplest possible dynamic page.

It didn't build.

The setup

Nothing fancy. Fresh create-next-app, Next.js 16.3.1, two flags in next.config.ts:

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

Then a product page. No database, no external API, not even a real fetch, just a fake delay and the route's own params:

async function getProduct(id: string) {
  await new Promise((resolve) => setTimeout(resolve, 300));
  return { id, name: `Product ${id}`, price: 42 };
}

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

  return (
    <main className="p-8">
      <h1 className="text-2xl font-bold">{product.name}</h1>
      <p>${product.price}</p>
    </main>
  );
}

That's about as plain as a dynamic route gets. I expected next build to shrug and move on.

What actually happened

Error: Route "/products/[id]": Next.js encountered uncached or runtime data during prerendering.

`fetch(...)`, `cookies()`, `headers()`, `params`, `searchParams`, or `connection()` accessed outside of `<Suspense>` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.

Ways to fix this:
  - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access
  - [cache] For uncached data (`fetch`, database calls): cache the access with `"use cache"` (does not apply to `connection()`)
  - [block] Set `export const instant = false` to allow a blocking route

Full build failure. Exit code 1. For a page whose only "dynamic" behavior is reading a param that's obviously going to be there.

My first reaction was that this felt aggressive. My second reaction, after rereading it, was that this is the whole point of the release and I'd missed it by only skimming the changelog. Cache Components in 16.3 doesn't treat an unguarded dynamic access as a warning. It treats it as a decision you have to make, explicitly, before it'll ship your build. Stream it, cache it, or mark it blocking on purpose. No silent fourth option where it just works and you find out it was never instant three months from now.

The fix, and what it actually buys you

I took the option the error suggested first: wrap the part that awaits params in <Suspense>.

import { Suspense } from "react";

async function getProduct(id: string) {
  await new Promise((resolve) => setTimeout(resolve, 300));
  return { id, name: `Product ${id}`, price: 42 };
}

async function ProductDetails({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const product = await getProduct(id);
  return (
    <>
      <h1 className="text-2xl font-bold">{product.name}</h1>
      <p>${product.price}</p>
    </>
  );
}

export default function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  return (
    <main className="p-8">
      <Suspense fallback={<p>Loading product...</p>}>
        <ProductDetails params={params} />
      </Suspense>
    </main>
  );
}

Ran the build again:

Route (app)
┌ ○ /
├ ○ /_not-found
└   /products/[id]
  └ ◐ /products/[id]

○  (Static)             prerendered as static content
◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

That ◐ next to my product route is the actual feature. Next.js pulled out everything around the Suspense boundary, the shell, and prerendered it. The part that actually depends on which product you clicked streams in behind it. That's Cache Components' Partial Prerendering doing exactly what it's supposed to, a real route in a real build output, not a description from the release notes. It's also the same shell mechanism that Partial Prefetching, the client-side navigation feature 16.3 adds on top of this, depends on existing in the first place.

What this told me that the changelog didn't

Reading about Partial Prefetching, "a reusable shell per route, cached on the client," sounds like a nice-to-have you'd adopt when you get around to it. Hitting the build error told me something different: on a 16.3 app with Cache Components on, there's no version of "get around to it." Every uncached or runtime access Next.js finds during prerendering needs an answer, stream, cache, or block, the moment you turn the flag on. It's not gradual. It's a build gate.

That's a bigger adoption cost than "add two lines to your config" makes it sound, and I think that's exactly why Next.js ships next-cache-components-adoption as a first-party agent Skill now instead of leaving you to hunt down every unguarded params and cookies() call by hand across a real app. On a five-file test project this took me two minutes. On a real production route tree, I wouldn't want to do it without that tool, or without a very good sense of where every Suspense boundary in the app already is.

Where I'd actually start

If you're evaluating this for a real app: don't turn the flag on for the whole project and see what catches fire. Pick one route, ideally your simplest dynamic one, and watch what the build tells you it needs. It will tell you exactly what to do next. That part, at least, the error message gets right.

I wrote a longer breakdown of the full 16.3 release, what upgrades automatically with zero config changes, what Instant Navigations and Partial Prefetching actually change, and what shipped for AI agents, on my website if you want the whole picture before you decide whether to flip these flags on something real.

Has anyone else run the migration on an actual production route tree yet? I'd like to know what the first pass looks like on a real app.

React 19's useFormStatus Fixed My Prop Drilling. Then It Sat There Returning False

Shubhra Pokhariya — Wed, 12 Aug 2026 12:04:31 +0000

Part 1 was about waiting well. Part 2 was about not waiting at all. This one is about a value I needed in a component that never created it, and about the ten minutes I lost putting the hook in the one place it can't work.

If you've read Part 1 on useActionState and Part 2 on useOptimistic, both of those hooks answer a question from inside the component that called them. That was never a problem for a two-field newsletter form. It became one the day I split an order form into separate pieces, payment details in one file, the place-order button in another, and both of them needed to know the same thing: is this thing submitting right now.

The setup that made prop drilling look reasonable

Here's roughly what the form looked like before I touched useFormStatus at all.

import { useActionState } from "react";

function PaymentFields({ disabled }) {
  return (
    <fieldset disabled={disabled}>
      <input name="cardNumber" placeholder="Card number" />
      <input name="cardExpiry" placeholder="MM/YY" />
    </fieldset>
  );
}

function PlaceOrderButton({ pending }) {
  return (
    <button type="submit" disabled={pending}>
      {pending ? "Placing order..." : "Place order"}
    </button>
  );
}

function OrderForm() {
  const [state, formAction, isPending] = useActionState(placeOrder, {
    message: "",
  });

  return (
    <form action={formAction}>
      <PaymentFields disabled={isPending} />
      <PlaceOrderButton pending={isPending} />
    </form>
  );
}

Nothing about this is broken. It works. But isPending lives in OrderForm, and both children only exist to receive it and hand it to a disabled attribute. Add a shipping section, an order-summary sidebar, a coupon field that should lock during submission, and every one of them needs the same prop threaded through, whether or not anything else about them changes. I'd read that useFormStatus was built to skip exactly this, so I went looking for where to put it.

Where I put it first, and why it did nothing

My first instinct was to call the hook right where isPending used to live, in OrderForm itself, treating it like a drop-in replacement.

import { useFormStatus } from "react-dom";

function OrderForm() {
  const { pending } = useFormStatus(); // stays false forever

  return (
    <form action={placeOrder}>
      <PaymentFields disabled={pending} />
      <PlaceOrderButton pending={pending} />
    </form>
  );
}

I clicked "Place order." Nothing disabled. No console warning, no red error overlay, just a button sitting there fully clickable while the network tab showed a request in flight. My first guess was that placeOrder wasn't actually async, or that I'd broken something in the action itself. I spent a few minutes staring at the action function before I even looked back at the hook.

The actual answer is simpler and, once you see it, a little obvious. useFormStatus doesn't read state that OrderForm owns. It reads the status of the parent <form>, and at the moment that hook call runs, OrderForm is still deciding what to render. The <form> tag doesn't exist as anyone's parent yet, it's the thing being built. There's no ancestor for the hook to find, so it falls back to its default, unpending shape, and it stays that way no matter how long the real submission takes.

The rule underneath that: the component calling useFormStatus has to be a descendant of the form it wants to read, never the component rendering the form itself. Fixing it meant pulling the hook out of OrderForm and putting it somewhere further down the tree.

import { useFormStatus } from "react-dom";

function PaymentFields() {
  const { pending } = useFormStatus();
  return (
    <fieldset disabled={pending}>
      <input name="cardNumber" placeholder="Card number" />
      <input name="cardExpiry" placeholder="MM/YY" />
    </fieldset>
  );
}

function PlaceOrderButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "Placing order..." : "Place order"}
    </button>
  );
}

function OrderForm() {
  return (
    <form action={placeOrder}>
      <PaymentFields />
      <PlaceOrderButton />
    </form>
  );
}

Same markup, same behavior at a glance, and suddenly pending flips correctly. Neither child receives anything from OrderForm anymore. Both just ask their parent form what's going on and get told the truth.

One detail that's easy to miss on the way there: this hook comes from react-dom, not react. useActionState and useOptimistic both live in react, so if you're moving through this series in order, typing import { useFormStatus } from "react" is a genuinely easy slip, and it fails in a way that doesn't tell you what went wrong either.

The part I didn't expect: it's watching more than a boolean

Once pending worked, I assumed that was the whole hook. It isn't. Calling it gives you an object with three more properties riding along, and I only found a real use for them once I stopped treating useFormStatus as a fancy boolean.

const { pending, data, method, action } = useFormStatus();

data is the FormData currently being submitted, available only while something is in flight. I used it to make the button say something more specific than a generic spinner label:

function PlaceOrderButton() {
  const { pending, data } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? `Placing order for ${data.get("email")}...` : "Place order"}
    </button>
  );
}

data is null the rest of the time, so that .get("email") call only runs safely because it's tucked inside the pending branch of the ternary. Pull it out and call it unconditionally, and the component throws the first time it renders idle.

method is where I got tripped up briefly, because I assumed it would mirror whatever method attribute I'd have put on the form. It doesn't work that way once you're using a function-based action. Any form using the action prop with a function, which is the entire reason this hook has something to track in the first place, submits as 'post' regardless of anything else you configure. You'd only see 'get' here on a form using a plain URL string as its action, or no action prop at all, and the docs only commit to one thing about that case: action itself comes back null. They stay quiet on pending and data, and since only function-based actions actually run through React's Transition tracking, that's not a combination I'd build anything around.

action is a reference back to whatever function you passed to the form's action prop. It's null for a form with no function-based action, and it's also null if there's no parent form at all, which means a falsy value here doesn't automatically tell you which of those two is true. I hit this once trying to conditionally render something based on whether action existed, and had to remind myself both cases collapse to the same falsy check.

The reused-component trick I didn't plan for, and the one I got burned by

The nicest surprise came later, almost by accident. PlaceOrderButton wasn't just used on the checkout page. It got reused, unmodified, on a "save draft order" form elsewhere in the app. I expected to need some kind of context or ID to tell it which form it belonged to. I didn't. useFormStatus resolves the nearest ancestor form independently everywhere it's rendered, so the same component read the correct pending state on both forms without a single line of extra wiring. That's not an edge case worth working around, it's a real reason to build small, reusable status-aware components in the first place.

The edge case that did surprise me went the other direction. Somewhere in an admin panel, a designer had wired a button outside its form using the HTML form="orderForm" attribute instead of physically nesting it. Pure HTML, no React opinion needed, and it submits the form fine. useFormStatus inside that button read as permanently not-pending, even while the form it was technically attached to was mid-submission. The hook walks the component tree, not the DOM-level form attribute association, so as far as it's concerned, that button was never a child of anything. Worth knowing before it surprises you in a codebase that uses this attribute anywhere.

Where I stopped reaching for it

Not every form needed this. On a two-field signup form with a single button in the same component, useActionState's own isPending, read directly where the hook was called, did the job without adding a second hook and a second rule to remember. useFormStatus earns its place once a form's parts genuinely live in separate components, not before.

And it only ever tells you about a submission already underway. useFormStatus isn't a validation API, it tells you what the form is doing once submission has started, not whether that submission should have been allowed to start in the first place. That decision still belongs upstream, in the action function or wherever else you're handling the submit.

Where useActionState, useOptimistic, and useFormStatus actually sit

Three parts into this series and the boundaries finally made sense to me as one picture instead of three separate hooks to memorize. useActionState owns a result and reacts to it, from wherever it was called. useOptimistic shows the finished UI before the server has actually agreed to it. useFormStatus answers one question, is this form pending, from any component underneath it, with nothing passed down to make that possible.

The distinction that finally made it stick for me: useActionState's isPending follows an Action, specifically the one dispatched through that hook call. useFormStatus's pending follows a form, whichever <form> happens to be its nearest parent, regardless of which component or which action put it there. That's why the same PlaceOrderButton worked unmodified on two different forms with two different actions later on. It was never watching an action. It was watching whatever form it happened to be sitting inside.

They stack without fighting each other. The order form I started with ended up using two of the three, useActionState in the parent owning the result, useFormStatus in every child section reading the same pending state independently.

I wrote the full breakdown on my site, including the complete four-section checkout example combining both hooks, the exact difference between this and useActionState's own isPending, and a side-by-side table for picking the right one: React 19 useFormStatus Explained.

If you want to test what you just learned, I also put together a short React 19 useFormStatus Quiz.

If you've built a form where the submit button lives three components away from the one managing the submission, it's worth checking where you actually called the hook before you assume something's broken. I know that's exactly where I lost ten minutes I didn't need to.

I Know the Recipe. I Miss the Winter Kitchen.

Shubhra Pokhariya — Sat, 08 Aug 2026 17:16:03 +0000

This is a submission for Frontend Challenge - Comfort Food Edition, CSS Art.

Inspiration

When I first read Comfort Food, my mind immediately went somewhere I haven't visited in years.

Not to pizza. Not to desserts. Not even to my favorite recipes.

It went back to my childhood kitchen.

During winter, even though we had a gas stove, my mother would often light our clay chulha. The kitchen felt warmer, the fire crackled softly, and one by one the phulkas would puff over the flame.

I still remember sitting there with my father and siblings, all of us eating from the same plate while waiting for the next phulka to arrive. It wasn't a special recipe. Just wheat flour, water, fire, and my mother's hands.

I've eaten many wonderful meals since then, but somehow those simple phulkas are still the first thing that comes to mind when someone asks me about comfort food.

I still remember how she would quietly place another phulka in front of me before I could even say I was full. If I protested, she'd smile and insist, "Just one more." Somehow, there was always one more.

Today I still love cooking. I know exactly how to make soft phulkas myself. But every now and then I realize I was never missing the recipe.

I was missing that winter kitchen. That feeling of waiting together. That warmth.

Somewhere while writing this, I stopped thinking about the challenge. I wasn't writing a submission anymore. I was simply writing down a memory I never wanted to forget.

Before anyone else reads this, I already know who I want to send it to first. My siblings. Because they'll know exactly which kitchen I'm talking about.

Demo

View the live demo on CodePen

What you're looking at: a clay chulha, firewood at the opening, flames glowing between the sticks, and a phulka cooking on the tawa. Nothing else. I wanted to keep the scene simple and let the story carry everything that isn't visible in the CSS.

The interaction: tap the phulka. It rises and settles, and one line stays on screen for a moment. I never missed the recipe. I missed the winter kitchen.

Journey

As a frontend developer, I wanted this project to be more than drawing food with CSS. I wanted to get the shape right, because the shape is the first thing anyone who grew up around a chulha will recognize, and the first thing that would look wrong to them if I got it wrong.

My first pass was a rounded dome. It looked warm, but it didn't look like a chulha. It read more like generic firelight. The chulha I remember has a solid, tapered clay body with a flat cooking surface on top. I reshaped the base and used layered gradients and border-radius to give the clay body its rounded, hand-built form, then moved the fire into a proper opening at the front instead of letting the flames float above the structure. That single change did more for the piece than every gradient I'd added before it.

The firewood took a few tries. Real sticks angle outward from the opening at different rows, not in a neat fan, so I gave each one its own rotation and length instead of repeating one shape three times. The flames sit low among the sticks now, several small uneven tongues instead of a few tall symmetrical ones, each flickering on its own timing so they never move in sync.

The phulka's lighting was the detail I'm proudest of getting right. The fire sits below and in front of it, so the warm highlight has to come from underneath, not from a generic top-left light source the way most CSS food art defaults to. Once I flipped that, it stopped looking like a painted circle and started looking like something actually sitting near heat.

The puff interaction runs on a single checkbox and the :has() selector. No JavaScript anywhere in the file. Tap the phulka, it lifts with a spring easing, and the line fades in at the top of the scene. prefers-reduced-motion turns off the fire and smoke animations and settles everything into a still, warm frame for anyone who needs that.

I started with more in the frame, a rolling pin, a cloth, even the whole kitchen at one point. Every version I stripped back felt more honest than the one before it. I realized I didn't need to recreate the entire kitchen to tell the story. The kitchen, my mother, my siblings, the warmth, and those hot phulkas are all part of the memory, but the chulha and the phulka are what I could recreate in CSS without trying to turn the memory itself into an illustration. So I kept the scene simple: the chulha, the fire, and the phulka. Everything else lives in the story behind it.

Comfort food isn't always the most elaborate meal. Sometimes it's the simplest one, because what we remember isn't the recipe. It's the people we shared it with.

I hope everyone who sees this remembers a kitchen that instantly takes them back home, wherever home may be.

Built with pure CSS. No JavaScript, no frameworks, no libraries.

React 19's useOptimistic Fixed My Instant UI. Then Combining It With useActionState Broke My Reset Button

Shubhra Pokhariya — Tue, 04 Aug 2026 16:39:10 +0000

Part 1 was about waiting well. This one is about not waiting at all, and about a couple of mistakes I made along the way that are worth walking through in the open.

If you read Part 1 on useActionState, you already know the shape of the problem it solves: three hand-rolled state variables, a try/catch/finally, and a pending flag you're hoping stays in sync with reality. useActionState fixes that for the "wait for the server, then show the result" case, and I closed that piece by saying useOptimistic was the next hook worth learning. This is that piece. But some interactions never wanted to wait in the first place. A comment posts. A like fires. A checklist item gets ticked off. The user expects to see the outcome the instant they act, not the instant the network agrees with them.

That's the gap useOptimistic fills. And building a real example that combines it with useActionState is what exposed two mistakes I'd made without realizing it.

The old trick, and why it quietly lied

Before this hook existed, "instant" UI usually meant something like this:

function handleLike() {
  setLiked(true); // update now, hope the request agrees later
  fetch("/api/like", { method: "POST" }).catch(() => {
    setLiked(false); // manually undo it if the request fails
  });
}

It works, until it doesn't. Forget the catch block and a failed request leaves the UI lying to the user forever. Get a second click in before the first request resolves and you're racing two local booleans against two network calls with no ordering guarantee between them. I shipped a version of this on a follow button once and spent an evening figuring out why the count would occasionally drift by one after a flaky connection. The state wasn't wrong because of a typo. It was wrong because nothing was actually managing the relationship between what I was showing and what was confirmed.

useOptimistic manages exactly that relationship, and it does it without you writing a single line of manual rollback logic, as long as you actually wire it up right. Keep reading, because I didn't, on the first pass.

What it does, briefly

const [optimisticState, setOptimistic] = useOptimistic(value, reducer?);

value is your real, confirmed state, the thing you'd render if nothing were in flight. optimisticState matches value right up until you call the setter inside a Transition, at which point it temporarily reflects whatever you passed in. Once the Transition settles, optimisticState collapses back to value. Not a value you have to reset. Not a flag you have to flip back. It falls back on its own, because that was always the only thing it was ever equal to once nothing's pending.

I go through the full API, the updater-function-versus-reducer decision, and the edge cases in the complete useOptimistic tutorial, so I won't repeat that ground here. What I want to get into is what happens when useActionState and useOptimistic end up in the same form, specifically around resetting it, because that's where things stopped being simple.

Combining them: a comment box

Here's the version I ended up with, after fixing what I got wrong the first time around.

import { useActionState, useOptimistic, startTransition } from "react";

function CommentBox({ comments, onConfirmed }) {
  async function postComment(previousState, formData) {
    if (formData === null) {
      return { error: null };
    }
    const text = formData.get("comment");
    if (!text?.trim()) {
      return { error: "Comment can't be empty." };
    }
    const saved = await saveComment(text);
    startTransition(() => onConfirmed({ id: saved.id, text }));
    return { error: null };
  }

  const [state, formAction, isPending] = useActionState(postComment, {
    error: null,
  });

  const [optimisticComments, addOptimisticComment] = useOptimistic(comments);

  async function handleSubmit(formData) {
    const text = formData.get("comment");
    const id = crypto.randomUUID();
    addOptimisticComment((current) => [...current, { id, text }]);
    return formAction(formData);
  }

  function handleReset() {
    startTransition(() => formAction(null));
  }

  return (
    <div>
      <ul>
        {optimisticComments.map((c) => (
          <li key={c.id}>{c.text}</li>
        ))}
      </ul>
      <form action={handleSubmit}>
        <input name="comment" disabled={isPending} />
        <button disabled={isPending}>Post</button>
        <button type="button" onClick={handleReset} disabled={isPending}>
          Reset
        </button>
        {state.error && <p role="alert">{state.error}</p>}
      </form>
    </div>
  );
}

CommentBox takes an onConfirmed callback the same way the upvote example in the full tutorial does, and it matters for the same reason. useOptimistic never updates the real comments prop for you. Something outside the hook has to. Once saveComment resolves, postComment calls onConfirmed with the confirmed comment, and the parent is expected to fold that into its own state, the same pattern as this:

function CommentThread({ postId }) {
  const [comments, setComments] = useState(initialComments);
  return (
    <CommentBox
      comments={comments}
      onConfirmed={(comment) =>
        setComments((current) => [...current, comment])
      }
    />
  );
}

Skip that wiring and you'll watch every comment you post disappear the moment the Transition settles, even though the server accepted it. That's not a hypothetical. It's the exact "shows you the future, doesn't make it real" mistake the full tutorial calls out, and it's worth restating here because it's easy to leave out of an example like this without noticing.

Notice too that onConfirmed is called inside its own startTransition, nested after the await. That's not decoration. If you update real state after an await inside a reducerAction, the docs are specific that it needs its own Transition wrapper, the same requirement the tutorial's edge cases section covers for the LikeButton example.

One more small thing worth calling out, because I got it wrong on an earlier draft of this same example: the id for each optimistic comment is generated with crypto.randomUUID() in handleSubmit, before it ever reaches the updater passed to addOptimisticComment. Not inside the updater itself. The reducer or updater you give useOptimistic has to be pure, the docs say so directly, and something like Date.now() called from inside it isn't. React can invoke that function more than once for the same update, and a fresh id each time it's called turns one comment into two different keys in your list.

Why remounting breaks more than the form

useActionState doesn't give you a way to clear its own state automatically. One common fix is bumping a key prop to force the whole component to remount, and on its own that's a reasonable option. It does reset the form. This is a different thing from requestFormReset, which React 19 also ships. That one clears uncontrolled DOM field values, not the state useActionState is holding on to, so it solves a narrower problem than the one we're talking about here.

The remount trick has a cost that doesn't show up until useOptimistic enters the picture. A remount doesn't just clear useActionState's result. It tears down and rebuilds the whole component tree underneath that key, and any useOptimistic state riding along in that same component gets torn down with it. If a Transition using that optimistic state hadn't settled yet, the optimistic item doesn't get replaced by the real one. It just vanishes.

My first fix for this, on an earlier pass, was to give the optimistic side its own reset branch too, mirroring the reset-signal pattern useActionState's own docs recommend. Something like:

function commentReducer(current, action) {
  if (action.type === "reset") return [];
  return [...current, action.item];
}

That looks reasonable and it's wrong in a way that only shows up once you trace what current actually holds. current isn't just the pending draft, it's the whole list, confirmed comments included. Returning [] unconditionally means clicking Reset would briefly wipe out comments that had already been saved, not just cancel whatever hadn't gone through yet. It settles back once the Transition resolves, since comments itself never changed, but for a moment the list a real user is looking at goes empty for no reason they'd understand.

The actual fix was realizing useOptimistic doesn't need a reset branch here at all. By the time Reset is even clickable, isPending is false, which means nothing is pending, which means optimisticComments already equals comments. There's nothing left for a reset to clear. The only state that genuinely needed a manual way to reset was useActionState's own return value, the error message, and that's exactly what formAction(null) handles in handleReset above. One piece of state actually needed telling to reset. The other one already had, on its own, which is the whole point of how useOptimistic works in the first place.

Resetting while an action is pending, and the AbortController pattern I got wrong

There's still a real question buried in here: what happens if Reset gets triggered while a submission is still in flight?

In an earlier draft I said React doesn't provide a cancellation mechanism for this. That was wrong, and worth correcting properly instead of quietly editing around it. The current useActionState reference has a section called "Cancelling queued Actions" that threads an AbortController through the payload passed to dispatchAction, letting a new dispatch abort whatever's still pending so it can run immediately instead of waiting in line. It's a documented recipe, not something you'd have to invent from scratch.

What I said next holds up better. Whether you should actually reach for that pattern depends on what the pending action does. The docs are blunt about it: aborting an Action isn't always safe, because cancelling the request client-side doesn't undo a mutation that already landed on the server. If saveComment already wrote to the database by the time an abort fires, the comment is still there no matter what the client thinks happened.

That's why handleReset above never reaches for AbortController. It calls formAction(null) the same way it calls every other dispatch, and because useActionState processes calls to dispatchAction in the order they arrive, the reset just queues behind whatever's still running instead of racing it. Disabling the Reset button while isPending is true isn't there to prevent a bug. It's there so the person clicking it isn't left wondering why nothing happened yet.

If you're building something where cancelling mid-flight genuinely matters, a search-as-you-type action where a stale result arriving late would actively confuse the user is a good example, that AbortController pattern is worth reaching for. For a mutation like posting a comment, letting it finish is the safer default, and as it turns out, the simpler one too.

The takeaway

useOptimistic asks very little of you on its own: show a value, let it fall back automatically. The two mistakes I walked through here both came from not trusting that. Forgetting to close the loop with onConfirmed meant the hook had nothing real to fall back to. Giving it its own reset branch meant fighting a job it was already doing correctly by itself. Trust the parts that are automatic, wire up the parts that aren't, and reset only the state that actually needs telling.

If you haven't read the full breakdown of useOptimistic, including the mistake that makes optimistic updates snap back even on success and when to reach for a reducer instead of an updater function, that's here: React 19 useOptimistic Explained. And if you're doing this inside a real Next.js app with Server Actions, cache invalidation, and error boundaries in the mix, the rollback pattern deep dive covers the parts that only show up once you're past the demo.

React 19's useActionState Showed Me Why Disabling My Submit Button Was Never Enough

Shubhra Pokhariya — Tue, 28 Jul 2026 10:50:54 +0000

Every form I ever shipped before React 19 needed the same three pieces of state, and I wired them up by hand every single time.

One for the result. One for whether it's submitting. One for the error. And at least once a sprint, I'd forget to reset one of them in the right place and spend twenty minutes staring at a button that wouldn't re-enable.

Here's the version I wrote for years, probably the same one you have sitting in a dozen components right now:

function OldSignupForm() {
  const [error, setError] = useState(null);
  const [isSubmitting, setIsSubmitting] = useState(false);

  async function handleSubmit(e) {
    e.preventDefault();
    setIsSubmitting(true);
    setError(null);
    try {
      await signup(new FormData(e.target));
    } catch (err) {
      setError(err.message);
    } finally {
      setIsSubmitting(false);
    }
  }

  return <form onSubmit={handleSubmit}>{/* ... */}</form>;
}

Three state variables. A try/catch/finally. And one bug waiting to happen the moment someone forgets that finally.

I didn't think this pattern was a problem until I actually sat down with useActionState and realized the workaround I'd been shipping to "fix" double submits was never actually fixing anything.

The habit that felt safe but wasn't

Here's what I mean. Most of us migrate a form like this by adding some version of:

function handleClick() {
  setLocalPending(true); // feels safe, isn't tied to anything real
}

On a fast connection, you'll never notice this is broken. On a slow one, that local flag can flip back to false before the actual request has resolved. A user on spotty wifi taps "Place Order" twice, maybe three times, because the button looked re-enabled for a split second. Each tap still goes through. React doesn't drop them, and it doesn't race them either. It queues them and runs them one after another, in order. So instead of one order, you've got three, each one processed like it was intentional.

That was the moment useActionState stopped feeling like just another hook to memorize. It started feeling like React quietly admitting they had watched enough of us get this wrong and finally built the fix.

What it actually does

const [state, formAction, isPending] = useActionState(fn, initialState);

You give it a function, React calls that function with (previousState, formData) whenever the form submits, and whatever it returns becomes your new state. isPending is tied to React's own transition tracking, not a boolean you're guessing the timing of.

A working example, no framework required, plain React:

import { useActionState } from "react";

async function subscribe(previousState, formData) {
  const email = formData.get("email");

  if (!email || !email.includes("@")) {
    return { success: false, message: "Enter a valid email." };
  }

  await new Promise((resolve) => setTimeout(resolve, 800));
  return { success: true, message: "You're subscribed." };
}

function NewsletterForm() {
  const [state, formAction, isPending] = useActionState(subscribe, {
    success: false,
    message: "",
  });

  return (
    <form action={formAction}>
      <input type="email" name="email" placeholder="you@example.com" />
      <button type="submit" disabled={isPending}>
        {isPending ? "Subscribing..." : "Subscribe"}
      </button>
      {state.message && <p>{state.message}</p>}
    </form>
  );
}

No onSubmit. No preventDefault. No separate pending flag to keep in sync. Swap disabled={isPending} in for that fake local flag, and the double-submit problem you thought you'd solved actually gets solved.

The part that genuinely surprised me

I assumed rapid clicks would race each other. Maybe the last one wins, maybe the first one does, classic race-condition territory. That's not what happens.

React queues every call to the action function and runs them sequentially. Each one waits for the previous one to finish before it starts. Click "Add to Cart" four times fast and it takes roughly four times as long to settle, not because anything's broken, but because call two is patiently waiting for call one's promise to resolve first. Nothing races. Nothing gets silently dropped.

Which means the real problem was never a corrupted database write. The problem is that every click still counts. Five taps on a slow connection means five processed actions, not one. disabled={isPending} isn't there to prevent a race, since there isn't one. It's there to stop someone from queuing up four actions they never meant to trigger in the first place.

One more thing worth knowing before it bites you. If an earlier call in that queue throws, React skips every call still waiting behind it. Catch your errors and return a state object instead of letting anything throw, or you'll lose queued actions you never even knew were sitting there.

async function submitOrder(previousState, formData) {
  try {
    const result = await placeOrder(formData);
    return { success: true, orderId: result.id };
  } catch (err) {
    return { success: false, error: "Something went wrong. Try again." };
  }
}

Two more traps I walked straight into

Stale closures. If your action function reaches into component-scoped variables instead of pulling straight from formData.get(...), you're one re-render away from acting on data that's already out of date. Prefer reading submitted values from formData instead of relying on values captured from an earlier render.

Forgetting there's no reset button. useActionState has no built-in way to clear its own state. The docs say so plainly. If you need a "start over" button, you have two real options. Teach your action function to recognize a reset signal as one of its inputs, or change the component's key prop to force a full remount. The reset-signal route is usually the less disruptive one, since it doesn't tear the DOM down to do it.

When I don't reach for it

If the interaction needs to feel instant, think a like button or a checkbox, anything where the UI should update before the server has even responded, useActionState will always feel a beat too slow for that. That's useOptimistic's job, and it's worth pairing the two once you've got the basics down.

And if it's a multi-step wizard with controlled inputs across steps that aren't all mounted at once, fighting the uncontrolled-form model useActionState is built on usually costs you more code than it saves.

The actual takeaway

The pattern you've probably been shipping, disable on click and hope for the best, was hiding the real issue instead of solving it. Every click still lands whether the button looks disabled or not. useActionState doesn't just cut boilerplate. It ties your pending state to something real, so the thing you thought you fixed actually gets fixed.

I wrote the full breakdown on my site, including the complete production signup example with field-level validation, the side-by-side comparison table against useState and useFormStatus, and the accessibility details around aria-busy and disabling inputs during a pending state: React 19 useActionState Explained

I honestly thought I understood this pattern until I started testing it properly. It turned out the problem wasn't React at all. It was the way I'd been managing pending state for years.

If you've been relying on your own pending state to handle form submissions, it's worth taking another look. I know I was surprised by what actually happens.

The Optimistic UI Race Condition That Only Showed Up on the Fifth Click

Shubhra Pokhariya — Tue, 21 Jul 2026 10:24:35 +0000

This is a submission for DEV's Summer Bug Smash: Smash Stories powered by Sentry.

I originally shared this debugging story on July 8. When Bug Smash was announced, it immediately came to mind because nothing crashed, nothing logged an error, and the application was still wrong.

The setup

Everything worked. I'd wired up useOptimistic on a task list, the checkbox flipped the instant you clicked it, no spinner, no half second lag, exactly the feeling I was going for. I demoed it to myself a dozen times and moved on.

That was the trap. Optimistic UI is designed to look right immediately. Looking right and being right are not the same claim.

The moment I stopped trusting the demo

Then I did the thing you're supposed to do before you actually ship anything. I clicked it stupidly fast, five times in a row, the way an impatient real user actually would.

The checkbox stayed visually fine. The database did not. Five overlapping requests had gone out, each one flipping the same boolean, landing in whatever order the network felt like that day. Nothing crashed. Nothing logged an error. The UI just quietly stopped matching what actually happened on the server, and I had no way of knowing from looking at the screen.

That is the bug that is easy to miss with optimistic UI specifically, because the whole point of optimistic UI is that it looks right immediately.

The fix isn't anything specific to useOptimistic

It's the same rule as disabling a submit button while a form is in flight, just applied per row instead of per form. Track which item has a request pending, and disable it until that request settles.

const [pendingId, setPendingId] = useState<string | null>(null);

function handleToggle(id: string) {
  setPendingId(id);
  startTransition(async () => {
    setOptimisticTask(id);
    try {
      await toggleTask(id);
    } finally {
      setPendingId(null);
    }
  });
}

<input
  type="checkbox"
  checked={task.completed}
  disabled={pendingId === task.id}
  onChange={() => handleToggle(task.id)}
/>

Here's what that actually looks like: five rapid clicks, one request.

One comment made me think harder

After the original post went up, Nazar Boyko left a comment that stuck with me.

He pointed out something I hadn't really separated in my own head. Disabling the checkbox only blocks clicks that go through that specific input. If the same toggle can ever be triggered another way, like a keyboard shortcut or somewhere else in the app, the disabled attribute is only one layer of protection. The real guard is the id keyed pending state, because that prevents the same operation from starting again regardless of how it was triggered.

He also mentioned that the rollback explanation was the part that clicked for him. Most examples manually flip the state back in a catch block without explaining why. Realizing that a plain toggle doesn't need that extra step was one of the biggest things I learned while digging into useOptimistic, so it was nice to hear that it helped someone else too.

That's one of my favorite things about writing technical posts in public. Sometimes someone doesn't find a bug in your code. They help you explain the idea more clearly or think about it from a different angle.

The rollback question that sent me down a rabbit hole

While I was in there, I went looking for how to properly roll back an optimistic update on failure, since obviously if the toggle fails, the checkbox needs to snap back to whatever it actually was.

Almost every example I found does this:

try {
  setOptimisticTask(id);
  await toggleTask(id);
} catch {
  setOptimisticTask(id); // flip it back again to "undo"
}

It works. It's also solving a problem that, for a plain toggle like this one, does not need solving. useOptimistic does not give you a second, independent piece of state you own. It gives you a temporary value layered on top of whatever state you passed in, for exactly as long as the transition is pending. The moment that transition settles, success or failure, React drops the temporary layer and renders from the real state again. If the real state never changed, because the request failed and nothing re-fetched, the checkbox reverts on its own. No second dispatch required.

There is one real exception. If the optimistic value is something the server has not confirmed yet at all, a new comment you added with a placeholder id before the database assigned a real one, there is no prior version of that item sitting in your base state to fall back to. A failed insert does not revert a flag, it has to remove something that only ever existed on the client. That is the one case where you keep your own local record of what you added and clear it yourself in the catch block. A toggle does not have that problem, since the value it flips already exists on the server either way.

The cache function question I didn't expect to have opinions about

Once the toggle worked, the next question was how to actually invalidate the cache after it. Next.js 16 gives you three ways to do this, and picking the wrong one either shows the user stale data or forces every page on the site to block on a single write.

For a checkbox someone is staring at as they click it, updateTag is the right one, since it expires the tag immediately so the page the user is currently on reflects their own write right away. If that same task count also fed a sidebar stat somewhere else on the site, one nobody is watching in real time, revalidateTag on that same tag lets it catch up a beat later instead.

One thing worth knowing if you are on a recent Next.js 16 version, revalidateTag now requires a second argument.

revalidateTag("tasks", "max"); // recommended in Next.js 16+

revalidateTag("tasks") alone is deprecated and will throw a TypeScript error.

What changed for me

I used to demo optimistic UI by clicking once.

Now I deliberately try to break it. Five rapid clicks. Slow networks. Repeated interactions.

Race conditions rarely announce themselves. They don't throw exceptions. They don't light up your console. They quietly wait for a user who is just a little more impatient than you were during development.

That checkbox looked perfect every time I demonstrated it. The bug was there the whole time. It was simply waiting for me to test it like a real user.

If you'd like the full walkthrough, including the rollback patterns, cache decisions, and the rest of the implementation, I've put it all here: shubhra.dev/tutorials/nextjs-16-useoptimistic-rollback-pattern

I Stopped Debugging at My Desk. Here's What Changed

Shubhra Pokhariya — Tue, 14 Jul 2026 11:43:12 +0000

I usually write here about Next.js, caching, and the bugs that steal your sleep. But this post is different. I want to share what happens before I write any of that code. The thing that has changed how I think about all of it.

Some developers go for a walk when they are stuck. Some make another cup of coffee. Some keep staring at the same file, convinced the answer is hiding somewhere between two lines of code. I usually go to my garden. Not because I am trying to escape the bug. Because I have learned that some problems become clearer the moment I stop trying so hard to solve them.

That was not something I planned. It happened slowly, the way most true things do. Over the past year, gardening quietly became part of my daily routine. Every morning before I open my laptop, I spend a little time with my plants. Sometimes I am watering them. Sometimes I am adding homemade compost. Sometimes I am just standing there, looking at what has changed since yesterday. It does not sound like work. But in many ways it prepares me for the work that is about to begin.

Yesterday evening, I was stuck. I mean properly stuck. The kind of stuck that sits heavy in your chest. A caching issue that did not quite make sense. Nothing was broken in an obvious way. The application worked. The data loaded. Most things behaved exactly as expected. Except one small detail. A page kept showing stale data long after it should have updated. I checked the obvious places first. Then I checked them again. I read the documentation. I followed the request flow. I looked at every cache boundary I could think of. Everything looked reasonable. When that happens, I have learned not to panic. If I am not making progress anymore, forcing myself to stare at the screen rarely helps. So I closed my laptop. Not because I was giving up. Just because I knew I needed a different perspective.

This morning, I did not open my editor. I climbed the stairs to my terrace instead.

The terrace was still damp from the night before. Rain always changes how the soil smells. The whole place felt softer, quieter, like the world had turned down its volume. I started checking my plants one by one. A tomato plant had grown taller overnight. The bottle gourd vine had reached another section of its support. A rain lily had quietly opened after the night's shower. None of these things happened quickly. They happened because nature keeps working even when nobody is watching. While turning the compost, my mind was not thinking about caching anymore. It was thinking about nothing in particular. And that is usually when interesting things happen. Without forcing it, I suddenly remembered one assumption I had made earlier. I had been looking at where fresh data entered the system. I had not looked closely enough at where the old data was still being reused. I saw it then. I should have seen it yesterday. That tiny shift in perspective was all I needed. When I went back inside, the fix took only a few minutes. The solution was not hiding in the garden. It had always been inside my own head. The garden simply gave my mind enough space to see it.

That experience is not unique. It has happened more times than I can count. And over time I realized gardening was not helping me because plants somehow make me a better programmer. It helps because gardening teaches habits that debugging also depends on. The first is observation. When you care for plants every day, you begin noticing tiny changes. A new leaf beginning to unfold. A stem leaning in a different direction. Soil drying faster than usual. A flower that is about to bloom. Nothing dramatic. Just small details that are easy to miss if you are moving too fast. Debugging feels surprisingly similar. Many bugs are not caused by huge mistakes. They are caused by one overlooked condition. One forgotten assumption. One small change that quietly affects everything around it. You do not always solve those problems by typing faster. You solve them by noticing more.

Gardening has also changed the way I think about patience. You cannot hurry a seed. You cannot ask a flower to bloom tomorrow instead of next week. You can only give it the right conditions and let time do its work. Software feels different because everything happens at incredible speed. We build. We deploy. We refresh. We expect immediate results. But good thinking does not always work at that pace. Sometimes your brain needs time in exactly the same way a plant does. Not because it is slow. Because growth has its own rhythm.

Another lesson I never expected to learn came from compost. At home, we make our own compost from vegetable peels, dried leaves, and other organic waste. At first glance, it does not look useful. It is just leftovers. But given enough time, those leftovers become the richest part of the garden. I sometimes think learning works the same way. The article you read six months ago. The bug you struggled with last year. The documentation you almost forgot. The conversation you had with another developer. None of it feels important on its own. Then one day, everything comes together. Knowledge has been quietly turning into something useful while you were not paying attention. That is why I never feel bad when I spend an afternoon reading instead of coding. Learning is not separate from building. It becomes part of every line you write later.

One of my favorite parts of the morning is simply walking through the garden before I do anything else. No headphones. No notifications. No endless scrolling. Just a few quiet minutes before the day becomes busy. Those minutes have become surprisingly valuable. They remind me that the world is much bigger than the editor on my screen. The code will still be there. The bug will still be waiting. But I will return with clearer eyes.

We spend a lot of time making software faster. We profile performance, improve queries, and remove unnecessary work. Somewhere along the way, I realized I had forgotten to do the same for myself. Not with another productivity system or another browser extension. Just by giving my mind a little room to slow down. For me, that is usually gardening. On some days, it is reading. On others, it is cooking, sitting quietly with my eyes closed, watching the stars, or simply standing in the rain for a few minutes. Your version might be completely different, and that is the point. It does not really matter what it is. What matters is having a place where your thoughts can wander without pressure. Ironically, that is often where the best ideas find you.

I still start most mornings the same way. Before opening my editor, I visit my plants. I check what is growing. I move a pot if it needs more sunlight. I turn the compost. I notice small things. Then I come back inside and begin writing code. It has become such a simple routine that I rarely think about it anymore. But looking back, I realize those quiet mornings have changed the way I approach software far more than I ever expected. The best solutions I have found did not always come from spending more hours in front of my screen. Many of them arrived after I stepped away for a little while. Sometimes the fastest way to solve a bug is not to keep looking at the code. Sometimes it is to give your mind enough room to see it differently.

If you are reading this and something unfinished is sitting heavy in your chest right now, I hope you find your own version of the terrace. It does not have to be a garden. It just has to be a place where you stop trying to solve everything, and let the answer come to you. You are not behind. You are not slow. You are simply growing at your own pace, in your own season, and that is exactly how it should be.

My Next.js 16 Optimistic UI Looked Perfect. Then Someone Clicked It Five Times Fast

Shubhra Pokhariya — Wed, 08 Jul 2026 07:43:35 +0000

Everything worked. I'd wired up useOptimistic on a task list, the checkbox flipped the instant you clicked it, no spinner, no half-second lag, exactly the feeling I was going for. I demoed it to myself a dozen times and moved on.

Then I did the thing you're supposed to do before you actually ship anything: I clicked it stupidly fast, five times in a row, the way an impatient real user actually would.

That's the bug that's easy to miss with optimistic UI specifically, because the whole point of optimistic UI is that it looks right immediately. Looking right and being right are not the same claim.

The fix isn't anything specific to useOptimistic

It's the same rule as disabling a submit button while a form is in flight, just applied per row instead of per form. Track which item has a request pending, and disable it until that request settles.

const [pendingId, setPendingId] = useState<string | null>(null);

function handleToggle(id: string) {
  setPendingId(id);
  startTransition(async () => {
    setOptimisticTask(id);
    try {
      await toggleTask(id);
    } finally {
      setPendingId(null);
    }
  });
}

<input
  type="checkbox"
  checked={task.completed}
  disabled={pendingId === task.id}
  onChange={() => handleToggle(task.id)}
/>

One item at a time, scoped per row, not a global lock on the whole list. The second click on the same checkbox now does nothing instead of firing a second request that races the first one to the database, which also means one fewer redundant write your database has to process for a click that never should have gone out in the first place.

Here's what that actually looks like: five rapid clicks, one request.

The rollback question that sent me down a rabbit hole

While I was in there, I went looking for how to properly roll back an optimistic update on failure, since obviously if the toggle fails, the checkbox needs to snap back to whatever it actually was.

Almost every example I found does this:

try {
  setOptimisticTask(id);
  await toggleTask(id);
} catch {
  setOptimisticTask(id); // flip it back again to "undo"
}

It works. It's also solving a problem that, for a plain toggle like this one, doesn't need solving. useOptimistic doesn't give you a second, independent piece of state you own. It gives you a temporary value layered on top of whatever state you passed in, for exactly as long as the transition is pending. The moment that transition settles, success or failure, React drops the temporary layer and renders from the real state again. If the real state never changed, because the request failed and nothing re-fetched, the checkbox reverts on its own. No second dispatch required.

There's one real exception, and it's worth knowing before you assume the automatic revert always has your back. If the optimistic value is something the server hasn't confirmed yet at all, a new comment you added with a placeholder id before the database assigned a real one, there's no prior version of that item sitting in your base state to fall back to. A failed insert doesn't revert a flag, it has to remove something that only ever existed on the client. That's the one case where you keep your own local record of what you added and clear it yourself in the catch block. A toggle doesn't have that problem, since the value it flips already exists on the server either way.

The cache function question I didn't expect to have opinions about

revalidatePath invalidates one path. revalidateTag invalidates every cache entry sharing a tag, wherever it's used, with stale-while-revalidate behavior. updateTag, Server Actions only, expires a tag immediately so the page the user is currently on reflects their own write right away.

For a checkbox someone is staring at as they click it, updateTag is the right one. If that same task count also fed a sidebar stat somewhere else on the site, one that nobody's watching in real time, revalidateTag on that same tag lets it catch up a beat later instead of forcing every page on the site to block on one write.

One thing worth knowing if you're on a recent Next.js 16 version: revalidateTag now requires a second argument.

revalidateTag("tasks", "max"); // recommended in Next.js 16+

revalidateTag("tasks") alone is deprecated, and current TypeScript definitions flag it as an error.

The error boundary detail that only matters if your error comes from data fetching

Last piece: what happens when the request just fails outright, not a validation error, an actual dropped connection. Next.js docs are clear that an error thrown inside startTransition still bubbles up to the nearest error.tsx, transition or not.

What I didn't know until I went looking: as of Next.js 16.2, error.tsx ships a second recovery prop, unstable_retry, sitting alongside the older reset. They're not interchangeable. reset wipes the error and lets the same children render again exactly as they were, no new fetch involved, so if the underlying data never loaded in the first place, you're just showing the same broken screen a second time. unstable_retry actually goes back to the server and re-renders the segment fresh, which is the one that fixes anything when the failure came from a fetch.

export default function TaskListError({
  error,
  unstable_retry,
}: {
  error: Error & { digest?: string };
  unstable_retry: () => void;
}) {
  return (
    <div role="alert">
      <p>Something went wrong loading your tasks.</p>
      <button onClick={() => unstable_retry()}>Try again</button>
    </div>
  );
}

reset still has a place, specifically when you want to clear an error and re-render without touching the network at all. For a segment whose entire job is showing fetched data, that's rarely the case.

Where the rest of this lives

I wrote the full version of this with the complete before/after code, the decision table for all three revalidation functions, and the Suspense boundary pattern for streaming a mutation's result without blocking the rest of the page, over on my site: "I Added Optimistic Updates to a Next.js 16 App. Here's Every Rollback Bug I Hit." It follows directly from the Server Actions bugs I wrote up in an earlier post, if you want the context on useActionState and why redirect can't sit inside a try/catch.

Has anyone else had an optimistic UI look perfect in every demo and then fall apart the moment a real user clicked faster than you did? I'd genuinely like to know if the rapid-click case is as common as it felt once I actually looked for it.

Note: AI used for image editing.

My Next.js 16 Auth Passed Every Test. Five Bugs That Only Showed Up When I Wired It Together.

Shubhra Pokhariya — Tue, 30 Jun 2026 06:01:36 +0000

The three-layer model works. Part 1 of this series is the invoice incident that proved it. Part 2 is the proxy.ts matcher gaps that fail silently. Part 3 is the mutation-layer auth check that gets skipped even when everything else looks solid. My kit implements this in Route Handlers rather than Server Actions, but the principle is identical: every mutation endpoint verifies the caller before touching data.

I built all three layers correctly. Then I tried to ship a complete auth kit on top of them.

Email and password login. Google and GitHub OAuth. Email verification. Password reset. Role-based routes. An admin panel with live database stats. A UI a real person would trust with a real password.

That is when the integration bugs appeared. Not architecture bugs. Wiring bugs. The kind that only exist once every piece is connected and real flows run through the whole thing.

Five of them. Here is exactly what happened.

Bug 1: The Cookie Write That Reported Success and Then Vanished

Login returned 200. Tokens in the response. Client wrote the cookie. The very next request redirected straight back to login.

I went to the JWT first. The JWT was fine. The proxy was fine. The cookie was simply not there on the next request.

Here is what was actually happening. After a successful login call, the client was writing the cookie with document.cookie = .... In certain browser and timing combinations on localhost, that write reported success. document.cookie.includes('auth_tokens') returned true immediately after the assignment. Then a few seconds later, gone. No error. No warning.

The fix was not about the timing. It was moving the write to where it belonged from the start.

// app/api/auth/login/route.ts
const COOKIE_NAME = process.env.NEXT_PUBLIC_AUTH_COOKIE_NAME ?? "auth_tokens";

// ... after building responseBody and cookieTokens ...

const response = NextResponse.json(responseBody, { status: 200 });

const isSecure =
  request.headers.get("x-forwarded-proto") === "https" ||
  request.nextUrl.protocol === "https:";

const maxAge = rememberMe === true ? 60 * 60 * 24 * 30 : 60 * 60 * 24 * 7;

response.cookies.set(COOKIE_NAME, JSON.stringify(cookieTokens), {
  httpOnly: true,
  sameSite: "lax",
  secure: isSecure,
  path: "/",
  maxAge,
});

return response;

httpOnly: true means no JavaScript on the page can read this cookie at all. A script injected through an XSS vulnerability still cannot steal the session token because the token is invisible to every script. The browser stores it automatically from the Set-Cookie response header. Nothing to silently vanish.

As Part 1 covered, the proxy reads the session from a cookie, not localStorage. httpOnly closes both issues at once: the proxy can see the cookie, and client-side scripts cannot touch it.

If the client is writing something the server should write, stop debugging the client write. Move it.

Bug 2: The Navigation That Never Reached the Proxy

Cookie fixed, server-set, httpOnly. Still redirecting back to login.

After the login API returned 200, the form called window.location.href. But before I landed on that fix I had tried router.push(redirectTo) first. That is where the second bug was hiding.

router.push is a client-side navigation. No real HTTP request fires. The browser has no reason to attach the newly set cookie to anything outgoing because nothing crossed the network. proxy.ts only sees real HTTP requests. A route change that stays inside React's router is invisible to it. This is the same boundary Part 2 covered when explaining why matcher gaps are invisible at the proxy level: the proxy cannot check what it never sees.

The login form uses window.location.href for exactly this reason:

// app/login/login-form.tsx
async function handleSubmit(e: FormEvent<HTMLFormElement>): Promise<void> {
  e.preventDefault();
  setError(null);
  setIsSubmitting(true);

  try {
    await login(email.trim(), password, rememberMe);
    window.location.href = redirectTo; // real HTTP GET, proxy sees the cookie
  } catch (err) {
    // ... error handling
    setIsSubmitting(false);
  }
}

window.location.href forces a full page reload. A genuine HTTP GET. The browser attaches every cookie it holds. The proxy sees it because this request actually crossed the network.

Bug 3: A Database Integer in the JWT Sub Claim

Cookie arriving correctly. Proxy still rejecting the token.

Debug logging showed the JWT decoding fine. Every claim present. The type guard in extractPayload kept failing on sub. typeof sub !== 'string' kept returning true even though the value looked like a user ID.

The database id column is SERIAL, a Postgres integer. When that integer got passed into jose's .setSubject() without an explicit cast, it was serialized into the token as a number. The extractPayload function checks typeof sub !== "string" and throws if that fails. It was doing exactly what it should. The claim was wrong because of an upstream assumption that never held for an integer primary key.

The fix is in lib/auth/jwt.ts on both signAccessToken and signRefreshToken:

// lib/auth/jwt.ts
export async function signAccessToken(
  payload: SignablePayload,
): Promise<string> {
  return (
    new SignJWT({
      role: payload.role,
      email: payload.email,
      permissions: payload.permissions,
    })
      .setProtectedHeader({ alg: "HS256" })
      // Always cast to string here. Postgres ids that come through as
      // numbers will otherwise get signed as numbers, and proxy.ts expects
      // sub to always be a string when it verifies the token.
      .setSubject(String(payload.sub))
      .setIssuedAt()
      .setExpirationTime(ACCESS_TOKEN_TTL)
      .sign(ACCESS_SECRET)
  );
}

String(payload.sub) on both signAccessToken and signRefreshToken. One word. The extractPayload type guard that catches this is correct. The claim was malformed, just not visibly, because a number and a number-as-string look identical in a console log.

This bug is invisible in development if test data uses string IDs. It only surfaces when a real SERIAL column meets a JWT library that validates claim types strictly.

Bug 4: OAuth Sign-In When the Same Email Already Has a Password Account

Email and password auth working end to end. Time to add Google and GitHub.

The OAuth flow itself is documented well enough. The question that actually needed answering: what happens when someone who already has a password account later clicks "Continue with Google" using the same email address?

The callback route handles three distinct cases:

// app/api/auth/google/callback/route.ts

// Case 1: they've signed in with Google before, google_id already set
let user = await db.queryOne<UserRow>(
  `SELECT id, email, name, role, is_active, google_id
   FROM authkit_test_users
   WHERE google_id = $1`,
  [googleUser.sub],
);

if (!user) {
  // Case 2: no google_id match, but email matches an existing row
  const existingByEmail = await db.queryOne<UserRow>(
    `SELECT id, email, name, role, is_active, google_id
     FROM authkit_test_users
     WHERE email = $1`,
    [normalizedEmail],
  );

  if (existingByEmail) {
    // Linking is safe here because Google has already verified this
    // email belongs to whoever is sitting at the browser right now.
    // email_verified gets set true at the same time, in case they
    // registered with a password earlier and never finished clicking
    // their own verification link.
    await db.query(
      `UPDATE authkit_test_users
       SET google_id = $1, email_verified = true
       WHERE id = $2`,
      [googleUser.sub, existingByEmail.id],
    );
    user = existingByEmail;
  } else {
    // Case 3: brand new person, create the row
    // password_hash stays null, role always defaults to 'user'
    const rows = await db.query<UserRow>(
      `INSERT INTO authkit_test_users
         (email, password_hash, name, role, is_active, email_verified, google_id)
       VALUES ($1, NULL, $2, 'user', true, true, $3)
       RETURNING id, email, name, role, is_active, google_id`,
      [normalizedEmail, googleUser.name ?? null, googleUser.sub],
    );
    user = rows[0] ?? null;
  }
}

The linking in Case 2 is safe specifically because of who verified the email. Google has already confirmed this email belongs to whoever is sitting at the browser. That is a stronger guarantee than most apps' own verification flow. The unsafe version of this pattern is linking accounts based on an email someone simply typed into a field with no third-party verification behind it.

Role always defaults to 'user' on new accounts. There is no code path a visitor can trigger that grants admin through a sign-in button.

GitHub needed one extra step Google does not. Google always returns a verified email with the basic profile request. GitHub does not. Many users set their email to private, so the profile response comes back with email: null. The fix is a second request to GitHub's emails endpoint, filtering for the address marked both primary and verified. No verified primary email means the account cannot sign in this way.

Both providers on the same sign-in screen. The three-case account lookup in Bug 4 is what makes this safe when the same email already exists from a password registration.

Bug 5: Forgot Password for an Account That Never Had a Password

This one does not show up until you have built both OAuth and email/password auth and put them in the same product.

A user registers with Google. Months later they land on the forgot password page and type in their email, because they have genuinely forgotten they always came in through the Google button and never set a password.

Without handling this, that person gets a password reset email for a password that has never existed. The link technically works. The experience makes no sense and they leave more confused than before.

The password_hash column stays null for every OAuth-only account. That is the check:

// app/api/auth/forgot-password/route.ts

if (!user.password_hash) {
  // This account signed in through an OAuth provider and never set a
  // password. Send a message pointing at whichever one they actually
  // used rather than sending a reset link for a password that doesn't exist.
  const provider = user.google_id
    ? "Google"
    : user.github_id
      ? "GitHub"
      : "Google or GitHub";

  try {
    await resend.emails.send({
      from: process.env.RESEND_FROM_EMAIL ?? "noreply@example.com",
      to: normalizedEmail,
      subject: `Sign in with ${provider}`,
      html: buildOAuthOnlyEmail({ name: user.name, provider }),
    });
  } catch {
    // Email failed to send, the generic response goes out either way
  }
  return NextResponse.json(genericSuccessBody, { status: 200 });
}

The buildOAuthOnlyEmail function is in the same file. It generates a plain HTML email that tells the person their account was created with that provider and links them back to the sign-in page. No password reset link. No confusion.

The browser response is identical regardless of which branch runs:

const genericSuccessBody = {
  message:
    "If an account exists for this email, we've sent you instructions.",
};

Same message, same 200 status, whether the user has a password, uses OAuth, or does not exist at all. This endpoint should never confirm or deny which email addresses are in your system.

Same page, same response to the browser, for every email submitted. The branching on password_hash happens entirely on the server side.

What Shipped After These Five Bugs Were Gone

Registration with bcrypt hashing, a live password strength meter, and a terms checkbox. Email verification and password reset through Resend with separate token lifetimes: 24 hours for verification, 1 hour for reset. Google and GitHub OAuth with the account linking logic above. Role-based routes. An admin panel pulling live counts from the database. A 403 page instead of a crash when someone hits a route their role does not cover.

The data layer ownership pattern from Part 1 runs on every query. WHERE user_id = $1 inside the SQL, not as a wrapper around the result. The auth check pattern from Part 3 runs on every mutation endpoint. Verify the caller before touching data. Both are in the kit exactly as written in the earlier posts in this series.

Live database counts in the admin panel. Anyone without the admin role who hits this URL directly lands on the 403 page instead.

One Tailwind v4 issue worth naming because it produces zero errors. Next.js 16 on Turbopack has a documented file watching problem where Tailwind's class detection misses .tsx files entirely. Clean build, no warnings, completely unstyled HTML. The fix:

/* app/globals.css — add after @import "tailwindcss" */
@source "../app/**/*.{ts,tsx}";
@source "../components/**/*.{ts,tsx}";
@source "../lib/**/*.{ts,tsx}";

Three lines and everything renders correctly.

Three Things for the Auth Checklist After This Build

Parts 1 through 3 of this series built a checklist of things that work locally and break in production. Three more belong on it now.

Client-side cookie writes can silently vanish with no error. Move the write to the server with response.cookies.set(). That is where it belongs regardless of any timing issue.

router.push after login does not trigger the proxy. If the proxy needs to read a freshly set cookie on the next request, that request has to be a real HTTP GET. Use window.location.href.

Wrap integer primary keys in String() before signing a JWT. .setSubject(String(payload.sub)) not .setSubject(payload.sub). A SERIAL column is an integer. The JWT type guard that catches this is correct. The claim is malformed, just not visibly so.

Get the Auth Kit

Everything in this series built into one kit: three-layer security, email and password, Google and GitHub OAuth, email verification, password reset, role-based access, admin panel, and deployment guide. Next.js 16 Auth Kit at shubhra.dev

The full implementation tutorial with every code file, database schema, and deployment notes is at I Built a Next.js 16 Auth Kit. Every Edge Case I Found Is in Here.

Has anyone else hit the OAuth forgot-password edge case before it shipped? I started paying attention to it after this build. More common than I expected. People who register with Google genuinely try the forgot password page later because they forget how they originally signed in. Curious whether others caught it early or found out from a user.

Note: AI used for image editing.

Next.js 16 Server Actions Security: The Auth Check Most Developers Miss

Shubhra Pokhariya — Wed, 24 Jun 2026 17:24:06 +0000

I keep seeing it on code reviews. Proxy solid. Auth on every Server Component. Header direction correct.

Then I look at the Server Actions.

No auth check. Not one. The page that renders the button is protected. The action behind the button accepts whatever the caller sends -- any valid session, any resource ID, no ownership verification anywhere.

'use server' doesn't add authentication. It exposes an HTTP endpoint. Anyone with a valid session cookie and a cURL command can call it directly, no UI required.

That's what this post covers.

What "use server" does, and what it does not do

When you add 'use server' to a file or a function, you're telling Next.js to move that code to the server and expose it as a callable endpoint. That's all it does.

It does not add authentication. It does not check who is calling. It does not verify that the caller has any session at all. From the official Next.js 16 docs:

Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation.

Public-facing API endpoints. That's exactly what they are. Anyone who can construct a POST request to the right URL can call your Server Action. No browser required. No UI required. A cURL command with a valid session cookie is enough.

The shift that matters: when you write a Server Action, you're not writing an internal helper that only runs when a user clicks a specific button. You're writing a public HTTP endpoint that also happens to be invokable from a button. Completely different from a security standpoint.

Next.js does give you two protections out of the box worth knowing about. Action IDs are encrypted and non-deterministic, recalculated between builds, so old IDs stop working after a deploy. Unused Server Actions are removed from the client bundle entirely through dead code elimination. Both things help reduce your attack surface. Neither one is authentication.

The gap that looks fine until it isn't

This is the pattern I keep finding on code reviews:

// app/dashboard/posts/[id]/page.tsx
import { verifySession } from '@/app/lib/dal'
import { deletePostAction } from './actions'

export default async function PostPage({ params }) {
  const session = await verifySession()  // Page is protected

  return (
    <div>
      <h1>Edit Post</h1>
      <form action={deletePostAction}>
        <input type="hidden" name="postId" value={params.id} />
        <button type="submit">Delete</button>
      </form>
    </div>
  )
}

// app/dashboard/posts/[id]/actions.ts
'use server'

import { db } from '@/lib/db'

export async function deletePostAction(formData: FormData) {
  const postId = formData.get('postId') as string

  // No auth check. The page already verified the user.
  await db.post.delete({ where: { id: postId } })
}

The page check runs at render time and confirms the user is authenticated before the UI appears. The action check never runs because nobody added one. The action will accept a delete request from anyone with any valid session, for any post ID, with no verification that the caller owns the post.

The fix is treating the action as its own entry point with its own verification:

// app/dashboard/posts/[id]/actions.ts
'use server'

import { verifySession } from '@/app/lib/dal'
import { db } from '@/lib/db'

export async function deletePostAction(formData: FormData) {
  const session = await verifySession()
  const postId = formData.get('postId') as string

  const post = await db.post.findUnique({ where: { id: postId } })

  if (!post || post.authorId !== session.userId) {
    throw new Error('Not found')
  }

  await db.post.delete({ where: { id: postId } })
}

Two changes. verifySession() runs first, independent of whether the page ran it. The ownership check runs before the delete.

Same error for "not found" and "not authorized" is intentional. Different error messages let a caller figure out which post IDs exist in your system. One generic error closes that.

The Data Access Layer: why it exists

Once you start adding auth checks, ownership checks, and business logic inside every action, the actions get long and hard to audit. I used to copy-paste the ownership check into every action that touched posts. Then I changed the logic in one place and forgot the other four. A user found the gap before I did. The Data Access Layer pattern fixed that permanently.

Centralize all auth logic and database access in a separate module marked with server-only. Keep your actions thin. Actions receive input, call DAL functions, handle Next.js-specific things like cache revalidation. That's it.

// app/lib/dal.ts
import 'server-only'
import { cookies } from 'next/headers'
import { decrypt } from '@/app/lib/session'
import { cache } from 'react'
import { redirect } from 'next/navigation'

export const verifySession = cache(async () => {
  const cookie = (await cookies()).get('session')?.value
  const session = await decrypt(cookie)

  if (!session?.userId) {
    redirect('/login')
  }

  return { isAuth: true, userId: session.userId as string }
})

server-only at the top is not decoration. It causes a build error if this module ever gets imported from a Client Component. The auth logic physically cannot reach the browser because the build won't allow it. That's stronger than any code review convention.

The cache() wrapper from React is worth understanding too. When verifySession() gets called multiple times during the same render pass, once from the page, once from a leaf component, once from a data function, React deduplicates those calls automatically. One cookie read, one JWT verification, one result shared across the render. No repeated work.

Now the DAL functions:

// app/lib/dal.ts (continued)
import { db } from '@/lib/db'

export const getUserPost = cache(async (postId: string) => {
  const session = await verifySession()

  const post = await db.post.findUnique({
    where: { id: postId },
    select: { id: true, title: true, content: true, authorId: true }
  })

  if (!post || post.authorId !== session.userId) {
    return null
  }

  return post
})

export const deleteUserPost = async (postId: string) => {
  const session = await verifySession()

  const post = await db.post.findUnique({ where: { id: postId } })

  if (!post || post.authorId !== session.userId) {
    throw new Error('Not found')
  }

  await db.post.delete({ where: { id: postId } })
}

And the action becomes thin:

// app/dashboard/posts/[id]/actions.ts
'use server'

import { deleteUserPost } from '@/app/lib/dal'
import { revalidatePath } from 'next/cache'

export async function deletePostAction(formData: FormData) {
  const postId = formData.get('postId') as string
  await deleteUserPost(postId)
  revalidatePath('/dashboard/posts')
}

The action does two things: call the DAL function and handle cache invalidation. Everything else lives in the DAL where it's reviewable and testable in one place.

The Layout trap that catches everyone once

A lot of developers put their auth check in a shared Layout component because it feels efficient. One check, covers everything under that route segment. The official docs have a specific warning about this:

Due to Partial Rendering, be cautious when doing checks in Layouts as these don't re-render on navigation, meaning the user session won't be checked on every route change.

What that means in practice: a user navigates to /dashboard, the Layout checks their session. They then navigate to /dashboard/billing. The Layout does not re-render. No session check runs for that navigation. If that user's session was revoked between those two navigations, the billing page renders anyway.

The fix is straightforward. Layouts fetch user data for display purposes, name in the nav, avatar, that kind of thing. The authorization check belongs in the page component or the DAL function it calls, not in the Layout.

// app/dashboard/layout.tsx
import { getUser } from '@/app/lib/dal'

export default async function DashboardLayout({ children }) {
  const user = await getUser()  // For display only, not auth enforcement

  return (
    <div>
      <nav>Welcome, {user.name}</nav>
      {children}
    </div>
  )
}

// app/dashboard/billing/page.tsx
import { verifySession } from '@/app/lib/dal'
import { getUserPermissions } from '@/app/lib/dal'
import { redirect } from 'next/navigation'

export default async function BillingPage() {
  const session = await verifySession()  // Runs on every navigation to this page
  const permissions = await getUserPermissions(session.userId)

  if (!permissions.includes('billing:read')) {
    redirect('/unauthorized')
  }

  // render billing content
}

Because verifySession() lives in the DAL and gets called from the page component directly, it runs on every navigation to that page regardless of what the Layout did or did not do.

Roles vs permissions inside actions

Roles are coarse and stable. They live in the session payload. Checking a role inside a DAL function costs nothing extra because the session is already decrypted:

// app/lib/dal.ts
export const verifyAdminSession = cache(async () => {
  const session = await verifySession()

  if (session.role !== 'admin') {
    redirect('/unauthorized')
  }

  return session
})

Permissions are granular and they change independently of session rotation. If you revoke a user's billing:export permission at 2pm, you want that to take effect immediately, not when their session next expires. That means a database call:

// app/lib/dal.ts
export const getUserPermissions = cache(async () => {
  const session = await verifySession()

  const permissions = await db.permission.findMany({
    where: { userId: session.userId },
    select: { name: true }
  })

  return permissions.map(p => p.name)
})

Because getUserPermissions is wrapped in cache(), if it gets called from both the page component and a leaf component during the same render, the database query runs once. Covered in Part 2 briefly, but the DAL pattern is where this actually becomes useful because the cache wrapper lives in one place and applies everywhere the function is called.

What to return from Server Actions

Server Action return values get serialized and sent to the client. If you return a raw database record, the client gets every column including ones it should never see. This happens by accident more than people realize:

// This sends passwordHash, stripeCustomerId, internalNotes to the browser
'use server'
export async function updateProfile(formData: FormData) {
  const session = await verifySession()

  return db.user.update({
    where: { id: session.userId },
    data: { name: formData.get('name') as string }
  })
}

// Return only what the UI needs
'use server'
export async function updateProfile(formData: FormData) {
  const session = await verifySession()

  await db.user.update({
    where: { id: session.userId },
    data: { name: formData.get('name') as string }
  })

  return { success: true, name: formData.get('name') }
}

When your DAL functions use explicit select statements, this is mostly handled automatically. The action returns what the DAL gives it. The DAL selects only the columns it needs. Nothing extra reaches the client.

Before you ship

Every Server Action calls verifySession() before touching data
Every mutation checks ownership before executing, not after
DAL functions use server-only and explicit select statements
Auth checks live in page components, not Layouts
Return values are DTOs, not raw database records
Test every action directly with cURL or a REST client before deploying, not just through the UI

That last one is the test. If hitting an action endpoint directly with a valid session cookie returns data or executes a mutation it should not, the UI protecting it does not matter.

Where this series ends

Part 1 was the invoice incident. One missing ownership check in a data function. Technically correct auth at every layer that actually existed, and one layer that did not exist.

Part 2 was the proxy.ts gate. The matcher failures that happen silently, the header direction bug, and getVerifiedUser() to close the header trust boundary.

This post is the layer that catches mutations. verifySession() in every Server Action independent of the page that rendered the button. Ownership checks before every mutation. The DAL pattern so the auth logic lives in one place. DTOs so the client only gets what it needs.

Three independent checks. One bug doesn't open the door.

I still see the missing action check on almost every code review I do. Not in the proxy. Not in the page. In the action, quietly accepting whatever the caller sent.

Full implementation with all three layers at Next.js 16 Authentication: The 3-Layer Security Model That Catches What proxy.ts Misses. Loading states, error handling, useActionState, and cache invalidation patterns in Server Actions are covered in Next.js 16 Server Actions: The Bugs That Only Show Up in Production.

Note: I use AI for editing and image generation, but the technical substance is from my own work.

I Got the proxy.ts Matcher Wrong for Three Projects Before I Understood Why

Shubhra Pokhariya — Wed, 17 Jun 2026 07:56:06 +0000

A few days ago I published a post about the three-layer auth model and the invoice incident that made me rebuild how I think about Next.js 16 auth. More people had hit the same thing than I expected.

One comment stopped me. Someone pointed out a real gap in how the forwarded headers work when the matcher misses a route. They were right, and I want to cover it properly here. But before that, I want to go through proxy.ts end to end, because in my experience the matcher is where most auth setups quietly break first, and it breaks in the worst way, no error, no warning, nothing in the logs.

Why the Name Changed

If you've been building with Next.js for a while, the rename felt arbitrary at first. middleware.ts to proxy.ts. Same location in your project, different filename, different export.

The Next.js team has been direct about why. The word "middleware" created real confusion. Developers coming from Express thought of it as a pipeline, stack things up, run them in order, app.use everything. That's not what this is and it led to people using it for things it was never meant to do: database calls, heavy business logic, session management.

What it actually does is sit at the network boundary in front of your app and intercept requests before they reach your routes. That's a proxy. The rename is the team saying: this has a specific job. Stop treating it like a general-purpose request pipeline.

The official docs are pretty clear:

Proxy is meant to be invoked separately of your render code. You should not attempt relying on shared modules or globals.

No database calls. No heavy logic. That belongs in the layers behind it, which is exactly what the previous post was about.

The Runtime Change That Actually Matters for Auth

middleware.ts defaulted to the Edge runtime. The Edge runtime had limited crypto support. Verifying JWTs with certain algorithms meant lighter libraries, specific workarounds, and sometimes things that just didn't work depending on which signing algorithm your tokens used.

proxy.ts runs on the Node.js runtime by default in Next.js 16. Full crypto support. jose works completely. Any standard JWT library works. No workarounds.

From the official version history:

v16.0.0: Middleware is deprecated and renamed to Proxy. Proxy defaults to the Node.js runtime

The Node.js runtime in proxy.ts is not configurable. The docs are explicit: the edge runtime is not supported in proxy, the runtime is nodejs, and it cannot be configured. Don't try to change it.

Edge runtime is still available through middleware.ts, which still exists in Next.js 16 for edge-specific cases like geographic redirects or A/B testing at the CDN level. But middleware.ts is deprecated. For auth, you want proxy.ts.

Migrating From middleware.ts

If you haven't done this yet, two options.

Full upgrade codemod for all Next.js 16 breaking changes:

npx @next/codemod@canary upgrade latest

Only the middleware migration if that's all you need:

npx @next/codemod@canary middleware-to-proxy .

After running either one, check these three things manually. Don't trust the codemod alone:

proxy.ts exists at your project root, same level as the app folder
The exported function is named proxy, not middleware
middleware.ts is gone

That third one is more important than it sounds. If you manually bumped the package version without the codemod, your old middleware.ts sits there, compiles clean, passes TypeScript checks, and does nothing at runtime. Routes that should be intercepted aren't. Redirects don't fire. No error anywhere. The file is just silently bypassed.

I covered this in the 4 places Next.js 16 broke my app post. This is the one that hurt the most because everything looks fine until a real redirect fails to fire in staging.

Also check next.config.js if you had skipMiddlewareUrlNormalize — configuration flags containing the middleware name are renamed in Next.js 16, so this is now skipProxyUrlNormalize. The codemod handles it, but worth verifying manually.

Building the proxy.ts Auth Gate

Three decisions in this code that look obvious but aren't. I'll walk through each one after.

// proxy.ts
import { NextResponse } from "next/server"
import type { NextRequest } from "next/server"
import { jwtVerify } from "jose"

// npm install jose
const JWT_SECRET = new TextEncoder().encode(process.env.JWT_SECRET!)

const PUBLIC_ROUTES = [
  "/login",
  "/register",
  "/forgot-password",
  "/reset-password",
  "/api/auth/login",
  "/api/auth/refresh",
  "/api/auth/logout",
  "/",
  "/about",
  "/pricing",
  "/blog",
]

const ROLE_ROUTES: Record<string, string[]> = {
  "/admin": ["admin"],
  "/dashboard": ["admin", "user", "moderator"],
  "/moderator": ["admin", "moderator"],
  "/api/admin": ["admin"],
  "/api/user": ["admin", "user", "moderator"],
}

export async function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl

  if (PUBLIC_ROUTES.some((route) => pathname.startsWith(route))) {
    return NextResponse.next()
  }

  const tokenCookie = request.cookies.get("auth_tokens")?.value

  if (!tokenCookie) {
    const loginUrl = new URL("/login", request.url)
    loginUrl.searchParams.set("redirect", pathname)
    return NextResponse.redirect(loginUrl)
  }

  try {
    const tokens = JSON.parse(tokenCookie)
    const { payload } = await jwtVerify(tokens.accessToken, JWT_SECRET)
    const role = payload.role as string

    for (const [route, allowedRoles] of Object.entries(ROLE_ROUTES)) {
      if (
        (pathname === route || pathname.startsWith(route + "/")) &&
        !allowedRoles.includes(role)
      ) {
        return NextResponse.redirect(new URL("/unauthorized", request.url))
      }
    }

    // Headers go on the request, not the response
    // Server Components read incoming request headers via headers()
    // Setting them on the response sends them to the browser instead
    const requestHeaders = new Headers(request.headers)
    requestHeaders.set("x-user-id", payload.sub as string)
    requestHeaders.set("x-user-role", role)
    requestHeaders.set("x-user-email", (payload.email as string) ?? "")

    return NextResponse.next({
      request: { headers: requestHeaders },
    })
  } catch {
    // Expired token, malformed JWT, bad JSON — all redirect to login
    // Same response for all three, no information leak about which failed
    const loginUrl = new URL("/login", request.url)
    loginUrl.searchParams.set("redirect", pathname)
    return NextResponse.redirect(loginUrl)
  }
}

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

Decision 1: The Matcher

This is where most auth setups break. And the way it breaks is the worst possible kind.

Without a matcher, the proxy runs on every request. Every CSS file. Every JS bundle. Every image. That's a JWT verification attempt on each one. When an unauthenticated user hits a CSS request, they get redirected to login, which has no token, which redirects to login again. Infinite redirect loop on static assets. Your app loads for authenticated users but something always feels slow and wrong, and the logs don't explain it.

The negative lookahead in the matcher above excludes static files and keeps the proxy on actual routes:

_next/static : compiled JS and CSS bundles
_next/image : image optimization endpoint
favicon.ico, sitemap.xml, robots.txt : metadata files
.*\\.png$ and the other image extensions : public folder assets

One behavior worth knowing: even if you exclude _next/data in your matcher, the proxy still runs for _next/data routes. This is intentional by design. If you protect a page, the proxy deliberately still covers the corresponding data route so you can't accidentally leave it exposed.

Matcher values must be constants. Statically analyzed at build time. Dynamic values, variables, anything computed gets silently ignored. Another way auth gaps get introduced with zero error output.

Decision 2: The Header Direction

I got this backwards the first time I wrote it.

// This is correct. Headers reach your Server Components
return NextResponse.next({
  request: { headers: requestHeaders },
})

// This is wrong. Headers go to the browser instead
// No error produced
return NextResponse.next({
  headers: requestHeaders,
})

headers() in a Server Component returns incoming request headers. If you set the x-user-id header on the response instead of on the forwarded request, every headers().get("x-user-id") call in your pages returns null. Every authenticated user gets redirected to login. Nothing in the logs to explain it. Took me way longer to debug than it should have.

Decision 3: The try/catch

The catch block handles three failure modes with one redirect: the cookie is valid JSON but the tokens object is malformed, the JWT is structurally broken, or the JWT is expired. All three end at login with no indication of which failed.

Different error responses for different failure modes tell an attacker something about the state of your system. One generic redirect tells them nothing.

The Header Trust Boundary

The proxy sets x-user-id on the request headers before forwarding. Server Components read it with headers().get("x-user-id"). Works fine when the proxy runs.

When does the proxy not run? When the matcher has a gap.

Add a new route, forget to check it falls inside the matcher pattern, the proxy never runs for that route. Nobody set x-user-id. Now a client sends their own x-user-id: someone_elses_id header on that unmatched route. The Server Component reads it. From inside the Server Component, a proxy-set header and a client-sent header look identical — there's no way to tell the difference.

What breaks: if you use that userId to query data, the data layer's AND user_id = $2 still scopes the query correctly. Actual records don't leak. But getUserPermissions(userId) now runs against the wrong user entirely. The attacker gets a different user's permissions back. No records exposed, but a real authorization failure on a specific route.

The fix is verifying the JWT directly from the cookie in the Server Component instead of trusting the forwarded header.

// lib/auth-server.ts
import { cookies } from "next/headers"
import { jwtVerify } from "jose"

const JWT_SECRET = new TextEncoder().encode(process.env.JWT_SECRET!)

type AuthUser = {
  userId: string
  role: string
  email: string
}

export async function getVerifiedUser(): Promise<AuthUser | null> {
  const cookieStore = await cookies()
  const tokenCookie = cookieStore.get("auth_tokens")?.value

  if (!tokenCookie) return null

  try {
    const tokens = JSON.parse(tokenCookie)
    const { payload } = await jwtVerify(tokens.accessToken, JWT_SECRET)

    return {
      userId: payload.sub as string,
      role: payload.role as string,
      email: (payload.email as string) ?? "",
    }
  } catch {
    return null
  }
}

Using it in a Server Component:

// app/dashboard/billing/page.tsx
import { redirect } from "next/navigation"
import { getVerifiedUser } from "@/lib/auth-server"
import { getUserPermissions, getUserInvoices } from "@/lib/data"

export default async function BillingPage() {
  const user = await getVerifiedUser()

  if (!user) {
    redirect("/login")
  }

  const permissions = await getUserPermissions(user.userId)

  if (!permissions.includes("billing:read")) {
    redirect("/unauthorized")
  }

  const invoices = await getUserInvoices(user.userId)
  return <BillingView invoices={invoices} />
}

Yes, this verifies the JWT twice on requests that go through the proxy. The proxy verifies at the network boundary, the Server Component verifies again at render time. That feels redundant. It isn't.

The proxy verification is the fast gate. The Server Component verification removes the trust dependency on the proxy having run at all. On a route where the proxy ran normally, the second verification takes a few milliseconds. On a route where the matcher had a gap, it's what closes the hole. Trusting a header any client can send on any unmatched route is not worth the few milliseconds saved.

Server Functions and the Proxy

Something in the official docs tucked into the execution order section that gets missed:

Server Functions are not separate routes in this chain. They are handled as POST requests to the route where they are used, so a Proxy matcher that excludes a path will also skip Server Function calls on that path.

If your matcher excludes a path, Server Actions on that path run without proxy coverage too. The docs explicitly say to verify authentication and authorization inside each Server Function, not rely on proxy coverage alone.

Same principle as the three-layer model. The proxy is the fast gate, not the complete answer.

Where proxy.ts Sits in the Request Flow

From the official docs, the actual execution order:

headers from next.config.js
redirects from next.config.js
proxy.ts
beforeFiles rewrites from next.config.js
Filesystem routes (public/, _next/static/, pages/, app/)
afterFiles rewrites from next.config.js
Dynamic routes
fallback rewrites from next.config.js

Third. After next.config.js headers and redirects, before anything in the filesystem renders. That's why it's cheap, it intercepts before any React component work starts.

Three Things to Check Before You Ship

JWT_SECRET in every environment. Always in .env.local. Easy to forget in staging or production. The jwtVerify call throws an opaque error when it's missing and authenticated users get sent to login with nothing in the logs that explains why.

Actually verify the migration ran. Check that proxy.ts exists at project root, the export is named proxy, and middleware.ts is deleted. Running the codemod and assuming it worked is not the same as checking. Manual upgrade with no codemod means the old file sits there silently doing nothing with zero warning.

Check the matcher every time you add a protected route. New route, check it falls inside the matcher pattern, check it appears in ROLE_ROUTES. Most auth gaps I've seen get introduced weeks after the initial proxy setup when someone adds a route and nobody goes back to verify coverage.

The proxy is the fast gate. It's essential and does its job well at the network boundary.

It can't answer ownership questions. It can't stop one user from seeing another user's data. And the forwarded header pattern has a real trust boundary issue on any route where the matcher has a gap.

Next post covers the Server Component authorization layer, roles versus permissions, why permissions need a database call that roles don't, and how the independent check at render time catches what the proxy structurally cannot.

Full implementation with all three layers: shubhra.dev/tutorials/nextjs-16-authentication-3-layer-security. The proxy setup in this post maps to Step 2 there. The getVerifiedUser utility above updates the Server Component pattern in Step 3 to close the header trust boundary gap.

Note: I use AI for editing and structure, but the technical substance is from my own work.

I Thought My Next.js 16 Auth Was Solid. One Afternoon Proved Otherwise.

Shubhra Pokhariya — Wed, 10 Jun 2026 07:04:58 +0000

A few months ago I was doing a final pre-release review on a client project before handing it over.

Protected routes were protected. Unauthenticated users got redirected. Tokens expired correctly. I had tested it three different ways and everything held up. I was confident enough to stop thinking about it.

Then I found something.

A user with a valid session, the right role, and a correct JWT could still request another user's invoice if they knew the ID. No error in the logs. No failed requests. The auth was technically correct at every layer I had actually built.

The problem was I had only built one layer and called it done.

That afternoon changed how I think about Next.js 16 authentication entirely. And I have been building it differently ever since.

One Thing to Check Before Writing a Line of Auth Code

If you are coming from Next.js 15, middleware.ts is deprecated in Next.js 16 and replaced by proxy.ts. Same location in your project, different filename, different exported function name. middleware.ts still works for Edge runtime use cases but will be removed in a future version.

// Before: middleware.ts
export function middleware(request: NextRequest) { ... }

// After: proxy.ts
export function proxy(request: NextRequest) { ... }

The auth-relevant change is the runtime. middleware.ts defaulted to Edge runtime, which had limited crypto support. Verifying JWTs in Edge required lighter libraries and sometimes workarounds depending on which algorithms your tokens used.

proxy.ts runs on Node.js runtime in Next.js 16. jose works completely. Any standard JWT library works. It removes the Node-crypto limitations that existed in the Edge runtime, which is a massive improvement for auth specifically.

# Handles the rename and all other Next.js 16 breaking changes
npx @next/codemod@canary upgrade latest

# Only the middleware migration if that is all you need
npx @next/codemod@canary middleware-to-proxy .

After running it: verify proxy.ts exists in your project root and the exported function is named proxy. Remove middleware.ts to avoid ambiguity. While it is still supported for Edge runtime, it is deprecated in Next.js 16 and the framework expects proxy.ts going forward.
Keeping both files can lead to confusion about which one is actually handling requests.

One important constraint: proxy.ts is designed for redirects, rewrites, header modifications, and direct responses. It is not intended for slow data fetching or full session management, and should not be used as your primary authorization layer. This is by design to keep the proxy focused on fast network boundary concerns.

Why proxy.ts Is Not Your Security Layer (Even Though It Looks Like One)

This is the thing almost every Next.js auth tutorial gets wrong. Not in an obvious way. In the way that passes all your tests and breaks in production.

proxy.ts runs at the network boundary before anything renders. It reads your session cookie, verifies the JWT, checks the role, and redirects or continues. Fast, essential, genuinely useful. Every auth setup needs it.

But it only sees URL patterns.

When it decided my user could access /dashboard/invoices, its job was done. It had no idea which specific invoice ID was in the URL, who owned that invoice, or whether the person requesting it had any right to see it. From the proxy's point of view, the URL matched, the role matched, the token was valid. Green light.

That gap is the invoice incident. The proxy was correct. It was just correct about the wrong thing.

// proxy.ts: role-based route protection, correct and valuable
const ROLE_ROUTES: Record<string, string[]> = {
  "/admin": ["admin"],
  "/dashboard": ["admin", "user", "moderator"],
}

// The proxy sees /dashboard/invoices/abc123 and approves it
// It has no way to know if abc123 belongs to this user
// Not a proxy bug. A category mismatch.

The proxy cannot answer ownership questions. Nobody can answer ownership questions from a URL pattern alone. You need the database for that. And the database is not where the proxy runs.

Treating proxy.ts as the complete security layer is not a configuration mistake. It is a mental model mistake. And it is the one almost every auth tutorial makes by stopping there.

The Check That Runs Even When Your Proxy Has a Gap

Server Components render when the page renders. That sounds obvious, but the implication is worth sitting with: Server Components run after the proxy and act as a second layer of enforcement. Even if a route slips past a misconfigured proxy matcher gap, this check still runs.

This is also where you catch the thing the proxy structurally cannot catch: permission-level decisions that depend on your database.

// app/dashboard/billing/page.tsx
import { headers } from "next/headers"
import { redirect } from "next/navigation"
import { getUserPermissions, getUserInvoices } from "@/lib/data"

export default async function BillingPage() {
  const headerStore = await headers()
  const userId = headerStore.get("x-user-id")

  // This check runs even if the proxy had a gap on this route
  if (!userId) {
    redirect("/login")
    return
  }

  // Role came from the JWT, fast, no DB call needed
  // Permissions need a DB call because they change more often than roles
  const permissions = await getUserPermissions(userId)

  if (!permissions.includes("billing:read")) {
    redirect("/unauthorized")
  }

  const invoices = await getUserInvoices(userId)
  return <BillingView invoices={invoices} />
}

The split between roles and permissions is intentional. Roles are stable enough to embed in a JWT. The proxy reads them without touching the database. Permissions change when you update access settings and you do not want to wait for a JWT to expire before that change takes effect. Roles in the proxy, permissions in the Server Component. That boundary matters.

The x-user-id header gets there because the proxy sets it before forwarding the request:

// Inside proxy.ts after JWT verification
const requestHeaders = new Headers(request.headers)
requestHeaders.set("x-user-id", payload.sub as string)
requestHeaders.set("x-user-role", role)

return NextResponse.next({
  request: { headers: requestHeaders },
})
// Headers go on the request, not the response
// Server Components read incoming request headers via headers()
// Setting them on the response sends them to the browser instead
// Your pages never see them if you get this backwards

I got this backwards the first time I wrote it. No error anywhere. The headers() call in the Server Component just returned null for both fields and the page redirected everyone to /login including fully authenticated admins. Spent an embarrassing amount of time on that one.

The Backstop That Would Have Caught the Invoice Bug No Matter What

Even if the proxy had a gap and the Server Component had a gap on the same day, this layer still holds.

Every data function that returns user-specific data takes a userId and uses it inside the query. Not as a convenience. As the actual access control.

// lib/data.ts

// This is what my data layer looked like before the incident
export async function getInvoice(invoiceId: string) {
  return db.query(
    "SELECT * FROM invoices WHERE id = $1",
    [invoiceId]
  )
}
// Anyone with any valid session could call this with any ID
// No error. No log entry. Just data returned to whoever asked.

// This is what it looks like now
export async function getInvoice(invoiceId: string, userId: string) {
  const invoice = await db.query(
    "SELECT * FROM invoices WHERE id = $1 AND user_id = $2",
    [invoiceId, userId]
  )

  if (!invoice) {
    throw new Error("Not found")
  }

  return invoice
}

The same error for "not found" and "not authorized" is intentional. Different errors let an attacker enumerate which IDs exist in your system. One generic error closes that information leak.

The ownership check lives inside the SQL. It cannot be misconfigured away. It cannot be missing from a route someone added last week. It cannot have a matcher gap. The authorization is in the query itself and the query runs every single time.

This is the layer that was missing from my app. The other two were correct. This one did not exist.

What All Three Layers Look Like on One Request

When an authenticated user hits /dashboard/invoices/abc123:

Request arrives

proxy.ts
  Reads auth_tokens cookie (written by your auth API on login)
  Verifies JWT (full Node.js runtime in Next.js 16, jose works completely)
  Checks role against ROLE_ROUTES
  Wrong role? Redirect to /unauthorized
  Correct role? Set x-user-id, x-user-role on request headers, continue

app/dashboard/invoices/[id]/page.tsx
  Reads x-user-id from forwarded headers, no re-verification needed
  Checks billing:read permission against DB
  Missing permission? redirect('/unauthorized')
  Has permission? Call getInvoice(id, userId)

lib/data.ts: getInvoice(invoiceId, userId)
  SELECT * FROM invoices WHERE id = $1 AND user_id = $2
  No row? throw new Error('Not found')
  Row exists? User owns it. Return data.

Component renders.

Three independent checks. A bug at any one of them does not open a door because the other two are still running.

One setup requirement worth knowing before you build this: the proxy reads the session from a cookie. If your auth client stores tokens in localStorage by default, the proxy cannot see them at all and will redirect every authenticated request straight to login. Make sure your auth setup writes tokens to a cookie. The proxy template in the full implementation reads a cookie named auth_tokens set on login.

The invoice incident had no bug in the proxy. No bug in the Server Component. One missing AND user_id = $2 in a data function. That was the whole thing.

The Mental Model in One Sentence

The proxy decides who can reach a route. The Server Component decides who can render a page. The data layer decides who can see a record.

All three are required. Any one of them alone will eventually have a gap. Two of them will eventually have a gap on the same day and you will be glad the third one exists.

The invoice incident was not a proxy failure. Not a Server Component failure. It was a missing data layer. The first two layers were correct. The third one did not exist.

That is the auth system most Next.js tutorials hand you. One layer. The other two are never mentioned.

This post is part of the Next.js 16 Auth: From Broken to Production-Safe series. The next post covers building the complete proxy.ts gate with working code: JWT verification with jose, the role routing config, the matcher pattern that most setups get wrong, and why the header forwarding direction breaks silently when you get it backwards.

The full implementation with all three layers, token refresh, Route Handler protection, and the complete Auth Guard client-side setup is at shubhra.dev/tutorials/nextjs-16-authentication-3-layer-security.

Has anyone else hit a data layer gap like this? I kept assuming the proxy covered everything until it very clearly did not. Curious how common this actually is across different projects.