DEV Community: Shubhra Pokhariya

I Tested generateStaticParams in Next.js Cache Components. My Layout Broke Twice

Shubhra Pokhariya — Wed, 09 Sep 2026 12:22:33 +0000

The last post here got picked apart in the comments in the best possible way. @nazar-boyko asked the sharpest version of the question I'd skipped entirely: if the ids are known at build time, does the page go fully static, or does Cache Components still want a stream, cache, or block answer regardless. @mudassirworks flagged the nested-component wrinkle, two server components independently awaiting params, and where the Suspense boundary actually has to sit. @suraj09, @glenallen, and @merbayerp circled the same architecture question from different angles, what happens once a layout and the page underneath it both depend on the same runtime data. @alexshev pushed on something none of us had done, turning a one-off fix into something that survives after the post is forgotten. None of it had a real answer from me at the time, so I built a fresh project and went and got one.

So I built a fresh test project, four routes this time instead of one, and ran every one of these to an actual answer.

Does generateStaticParams make a route static?

Short version: no. I gave a route three known ids up front and left the data access unguarded, same as the original test.

export async function generateStaticParams() {
  return [{ id: "1" }, { id: "2" }, { id: "3" }];
}

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

Build fails, and it names id 1 specifically, one of the exact three I told it about ahead of time. Knowing the id at build time and being allowed to skip the stream, cache, or block decision are two different things.

That part's a clean answer, but not the interesting one. The interesting part is what happens once you actually pick a fix, because the two fixes I tried don't produce the same result.

Wrap the data access in Suspense, and the build passes, but all three known ids come out marked as Partial Prerender. The data stays deferred behind the static shell, the same as it does for an id the route has never seen. Swap that for caching the data function instead, one word changed, "use cache" instead of a Suspense wrapper, and those same three ids flip to fully static, baked into the build output.

That's the real answer to Nazar's question. generateStaticParams decides which paths get attempted. Whether they end up static depends on the work the route performs for those params and how that work gets handled, not on the ids being known ahead of time by itself.

One more dead end worth flagging before you go looking for it yourself: I tried pairing generateStaticParams with the old dynamicParams = false option, expecting a 404 for anything outside the known set. dynamicParams still exists as a route segment config in Next.js generally, but it's disabled specifically once cacheComponents is on, so the build rejects it instead of applying it. In this Cache Components setup, unlisted ids are handled at request time instead.

The bug that took three attempts

This is the one I'd read even if you skip everything else, because it's the part that answers Suraj, Glen, and Mustafa's question, and it's the part that actually surprised me.

Setup: a layout and a page sharing a route segment, both reading the same id, both calling the same two data functions. Both unguarded. Build fails, expected.

My first move was the obvious one: fix the page, leave the layout alone, since I'd already handled the page's own component.

Still failed. Fixing the page did nothing for an unguarded params access in the layout above it. A Suspense boundary in the page can't reach back and cover work that already happened in the parent before the page even rendered.

So I fixed the layout too, wrapped the component reading the data in its own Suspense, the same move that had worked everywhere else so far.

Still failed. Same error. This is where I stopped guessing and ran next build --debug-prerender to get an actual trace instead of a route name.

It pointed at const { id } = await params;, sitting in the layout, above the Suspense boundary I'd just added. Not the data fetch inside the wrapped component. The line that produced the id in the first place.

I'd wrapped the component that used the id. I hadn't wrapped the line that produced it.

The real fix passes the whole params promise down and resolves it inside the wrapped child, instead of resolving it in the parent and handing over a plain value:

async function WorkspaceHeader({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const workspace = await getWorkspace(id);
  return <header>{workspace.name}</header>;
}

export default function WorkspaceLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ id: string }>;
}) {
  return (
    <div>
      <Suspense fallback={<header>Loading...</header>}>
        <WorkspaceHeader params={params} />
      </Suspense>
      <div className="p-8">{children}</div>
    </div>
  );
}

That builds clean. Same principle applied to the page underneath it.

One negative result worth keeping, since it's the mistake I'd expect someone to reach for first on a real app: I also tried leaving both layers completely unguarded and just caching the two shared data functions instead, assuming that would cover both callers at once. It didn't touch the failure at all. The unguarded operation was never the data fetch, it was await params itself, sitting outside any boundary in both places. Caching a function a broken access calls doesn't fix the access that calls it.

Mudassir's nested-sibling case turned out to follow the same underlying rule, just one layer shallower: two independent components both reading params, and wrapping only one of them left the other exposed. The fix isn't a specific boundary shape, it's making sure nothing reading runtime data sits outside every boundary, whether that's one shared wrapper or several separate ones.

What I'd actually check on a real app

Audit layouts before pages. A layout's unguarded access fails on its own terms, independent of anything you've already fixed below it, and it's the thing most likely to get missed because layouts don't feel like "the route" the way a page does.

When a fix doesn't work and the error still points at something you've technically wrapped, check where the await itself happens, not just where the result gets used. Resolving a promise above a boundary and passing the plain value into a wrapped child still counts as an unguarded access.

Alex, on the regression test question, here's what I landed on: a small script that rebuilds, then hits each fixed route including the unlisted-id case, since a plain build won't catch that on its own. Worth being honest that an HTTP check only proves the route responds, not which rendering mode it's using. That classification only ever comes from the build output itself.

I put the full four-route walkthrough, all the build screenshots, the exact debug trace, and the regression script in the full Next.js generateStaticParams and nested-layout walkthrough if you want the whole thing end to end rather than the condensed version here.

Has anyone hit this layout-versus-page split in a real production route tree yet? I'm curious whether the same params boundary issue shows up once several layouts start sharing data.

React 19 Actions: I Explained 3 Hooks Without Ever Explaining What an Action Is

Shubhra Pokhariya — Tue, 01 Sep 2026 07:30:35 +0000

Three parts into this series, and if you'd asked me to define the word sitting underneath every single hook I'd taught you, I'm not sure I could have done it cleanly. That's not false modesty. Go back and read Parts 1 through 3. I used the word "Action" constantly. I never once stopped to say what one actually is.

Part 1 opened with three state variables I'd hand-rolled for years, a result, a pending flag, an error, and showed how useActionState collapses all three into one call. Part 2 took a comment box and made it feel instant before the server had even replied. Part 3 let a submit button three components away read a form's pending state with zero props passed down. Three different problems, three different hooks, and every single one of them was quietly leaning on the same mechanism without me ever naming it out loud.

That's the gap this post closes. Not a new bug this time. The concept the last three bugs were all symptoms of.

The word I kept using and never defined

Here's the actual definition, straight from React's own docs, not a paraphrase I'm softening for effect. A function called inside startTransition is an Action. That's it. That's the whole qualifying test.

async function submitFeedback(previousState, formData) {
  const message = formData.get("message");
  await saveFeedback(message);
  return { sent: true };
}

That function above could sit in your codebase forever and never once behave like an Action. What flips the switch has nothing to do with anything written inside it. It's entirely about the doorway it walks through. Four doorways do this: a direct startTransition call, useTransition's version of the same call, a form's action prop taking a function instead of a string, or useActionState. Walk a function through any of them and it stops being a plain async function you're tracking by hand. What React takes over automatically is the Transition itself, the pending tracking underneath it. What it does not universally hand you is the function's return value. useTransition gives you isPending and nothing else, a raw startTransition call doesn't return anything at all. useActionState is the one doorway built specifically to catch that return value and hold onto it as state, which is exactly why isPending and a real result showed up together back in Part 1 and nowhere else in this series. More on the ordering side of this once useTransition shows up properly below.

Once that clicked for me, Parts 1 through 3 stopped looking like three separate hooks and started looking like three different windows onto the same room. useFormStatus reads the pending status of the nearest parent form, and now you know why, that pending status only exists in the first place because something wrapped the submission in a Transition. useOptimistic is the odd one out. It isn't a door into becoming an Action at all. It's a setter you call from inside one that's already running. Call it outside a Transition and it just won't behave the way Part 2 showed you.

Why any of this needed inventing

Part 1's opening line still holds up: every form needed the same three pieces of state, wired by hand, every time. That pattern wasn't unique to forms either. A delete button, a follow toggle, a checkout step, all needed the identical scaffolding rebuilt from scratch. React 19 added the ability to use async functions inside transitions in the first place, which is the foundation everything else in this series stands on. What you build on that foundation, whether you get a tracked result back or just a pending flag, depends on which of the four doorways you actually walk through. useActionState is the one that goes furthest, catching the return value as state. The others give you less by design.

`<form action={fn}>`, and the three things nobody tells you change

Before Actions existed, a form's only real path to running code was onSubmit, and that path came with requirements you had to remember every time. Call preventDefault, manually construct FormData from the event target, manage loading and error state by hand.

function OldForm() {
  function handleSubmit(e) {
    e.preventDefault();
    const formData = new FormData(e.target);
    // run the request, manage loading and error state yourself
  }
  return <form onSubmit={handleSubmit}>{/* ... */}</form>;
}

Swap onSubmit for a function passed straight to action and the mental model shifts more than the syntax suggests. Nothing calls preventDefault, not because you forgot it, but because React already knows this is an Action before the form ever fires, so the browser's default full-page reload was never going to happen in the first place. The function also stops receiving an event. It receives FormData directly, already built from every named field on the page, which is one less step you used to write by hand every time. And the request method itself stops being something you configure at all. A function passed to action always submits as POST, whatever you write in a method attribute sitting right next to it. That last one is the exact fact Part 3 ran into from the useFormStatus side, back when method kept coming back 'post' no matter what I expected walking in. It was never reading an attribute. It was reading the Action underneath it.

onSubmit still earns its keep for one job specifically. Anything that has to stop a submission before it starts, checking two password fields match, belongs there. By the time code inside the Action itself runs, the submission has already begun, so nothing in there can be the thing that prevents it.

Sync Actions exist. They're just not interesting

An Action doesn't have to be async. A plain synchronous function handed to the same four doors still counts, React still manages its lifecycle, but the pending window is usually too short to build UI around.

function resetSearch(previousState, formData) {
  return { query: "" };
}

The instant await shows up inside that function, everything from Parts 1 through 3 becomes worth having. React 18 required startTransition's callback to be synchronous. React 19 dropped that restriction, and that single change is what let useActionState, <form action={fn}>, and useTransition all accept async functions directly instead of you managing the async boundary by hand.

Client Actions and Server Functions are not the same word twice

Everything in this series so far has been a client Action, code that runs in the browser whether or not it talks to a server underneath. That version works identically in any React 19 setup, no framework required.

Server Functions are a related but genuinely separate idea, and they only exist in frameworks with Server Component support, Next.js being the obvious one. React's own docs are specific about the relationship here, and it's worth getting right instead of using the two terms interchangeably like I nearly did drafting this: a Server Function only becomes a Server Action once it's passed to an action prop or called from inside an Action. Not every Server Function is a Server Action. Every Server Action used this way is a Server Function.

"use server";

export async function submitFeedback(formData) {
  const message = formData.get("message");
  await db.feedback.create({ message });
}

That single formData argument is the shape a Server Function receives when it's handed directly to a form's action prop. It's worth flagging because it's not interchangeable with useActionState as-is, which always calls its function with (previousState, formData), the two-argument shape Part 1 introduced. Reusing server logic through useActionState means writing for that shape from the start, not dropping in a single-argument version and hoping React adapts it for you. It won't.

The fourth door: useTransition

useTransition hasn't come up by name once in this series, and the mechanism it exposes has been running underneath every single example anyway. Calling it gives you exactly two things back, an isPending flag and a startTransition function.

Every checkout example so far ran inside a <form>, which wraps its Action in a Transition automatically. useTransition is for when there's no form to lean on. Picture a wishlist heart icon sitting on a product card, no form anywhere near it, just a click handler that needs to hit the server and report whether it's pending.

import { useTransition, useState } from "react";

function WishlistButton({ productId, isSaved, toggleWishlist }) {
  const [isPending, startTransition] = useTransition();
  const [saved, setSaved] = useState(isSaved);

  function handleClick() {
    startTransition(async () => {
      setSaved(!saved);
      const result = await toggleWishlist(productId);
      startTransition(() => {
        setSaved(result.saved);
      });
    });
  }

  return (
    <button onClick={handleClick} disabled={isPending} aria-pressed={saved}>
      {saved ? "♥ Saved" : "♡ Save"}
    </button>
  );
}

Notice that second, nested startTransition wrapping setSaved after the await. If that looks familiar, it should, it's the exact same shape as onConfirmed getting wrapped in its own startTransition back in Part 2's comment box. That's not two separate patterns you happened to see twice. React only automatically tracks synchronous work as part of a Transition. Anything after an await needs its own startTransition call to still count, whether you're inside a comment form or a heart icon with no form in sight.

Notice too that the wishlist button above reaches for plain useState, not useOptimistic. That's not an oversight. This example exists to isolate what useTransition gives you entirely on its own, before any of the other three hooks get involved. In a real app you'd almost certainly reach for useOptimistic here instead, the exact instant-feedback job it was built for back in Part 2. Showing it with bare useState first is the only way to actually see what useTransition alone is doing.

Here's the part that's easy to miss and expensive to find out the hard way. Click that heart, unclick it, click it again fast, and a raw useTransition call gives you no guarantee about which result lands last. React says so directly: Actions inside a Transition don't guarantee execution order on their own. What's easy to assume, and what I nearly wrote into this section before checking, is that <form action={fn}> is just as exposed to that same problem as a bare useTransition call. It isn't. React's own docs group <form> actions together with useActionState as the two built-in ways that already handle ordering for you. It's raw useTransition, used on its own with nothing else wrapping it, that gets no such guarantee, the wishlist button above included. If you've been assuming that guarantee comes from Actions in general, it doesn't. It's specifically what useActionState and <form> actions add on top of the raw mechanism.

Where the four actually sit next to each other

You need to...	Reach for
Own a form's result and pending state in one place	`useActionState`
Show the finished UI before the server has confirmed it	`useOptimistic`
Read a form's pending state from a component that isn't managing it	`useFormStatus`
Run an Action outside a form and track its pending state	`useTransition`

They were never four competing answers to "which hook should I learn." They're four answers to four different questions that happen to share one mechanism underneath. The checkout form from Part 3 already proved it by combining two of them across four separate components, useActionState owning the submission, useFormStatus letting PlaceOrderButton read pending state with nothing passed down. Here's that same order form with a third hook layered on, a promo code that discounts the total the moment the form is submitted with it, before the server has confirmed anything.

import { useActionState, useOptimistic } from "react";
import { useFormStatus } from "react-dom";

async function placeOrder(previousState, formData) {
  const result = await submitOrder(formData);
  return { orderId: result.id, error: null };
}

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

function OrderForm({ cartTotal }) {
  const [state, formAction] = useActionState(placeOrder, {
    orderId: null,
    error: null,
  });

  const [displayTotal, applyDiscount] = useOptimistic(
    cartTotal,
    (current, discount) => current - discount,
  );

  function handleSubmit(formData) {
    if (formData.get("promoCode") === "SAVE10") {
      applyDiscount(10);
    }
    formAction(formData);
  }

  return (
    <form action={handleSubmit}>
      <p>Total: ${displayTotal.toFixed(2)}</p>
      <input name="promoCode" placeholder="Promo code" />
      <PaymentFields />
      <PlaceOrderButton />
    </form>
  );
}

useActionState still owns the real submission the same way it did in Part 3. useOptimistic shows the discounted total the moment the form submits with SAVE10 in the field, no waiting on submitOrder to confirm anything first, and it falls back on its own to whatever cartTotal currently is once the Transition settles. That fallback detail matters more than it looks. This trimmed-down version never actually updates cartTotal after submitOrder resolves, so the discount would vanish the instant the Action finishes, same trap Part 2 walked through with onConfirmed. A real version needs the parent to fold the confirmed, discounted total back into cartTotal once the order actually goes through, or the optimistic value has nothing real to settle into. useFormStatus still lets PlaceOrderButton disable itself with nothing passed down from OrderForm. Three hooks, one form, none of them stepping on the other's job.

The mistake I nearly baked into this whole series

Here's the trap I think this series set without meaning to. Teach one hook per post, three posts in a row, and a careful reader could walk away thinking the real task was picking a favorite, useActionState or useOptimistic or useFormStatus, as if only one of them belongs in a given form. That was never true. Composition was always the point. A real form rarely reaches for exactly one of these. It reaches for whichever two or three actually solve the piece of the problem sitting in front of it, and none of them are competing for the same job.

I built this series backwards on purpose, honestly, three concrete bugs before the concept underneath them, because I think a concept sticks harder once you've already felt the shape of the problem it solves. But it only works if the concept actually shows up eventually. This is that part.

If you want the deeper cut, sync versus async Actions in more detail, the full Server Functions section, and a proper FAQ, I wrote the complete version on my site: React 19 Actions Explained.

If you'd rather test what actually stuck first, I also built a 15-question quiz covering the same four APIs: React 19 Actions Quiz.

So here's the real question, the one I'd genuinely like an answer to. Which of these four have you already been using without knowing you were touching an Action? A <form action={fn}> you wired up because it looked simpler than onSubmit, a startTransition call you copied from somewhere without reading what it does, a button that felt laggy until you wrapped it in useTransition and never asked why that fixed it. Drop it below. I'm curious how many of us have been using this mechanism for months without a name for it.

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.

DEV Community: Shubhra Pokhariya

I Tested generateStaticParams in Next.js Cache Components. My Layout Broke Twice

Does generateStaticParams make a route static?

The bug that took three attempts

What I'd actually check on a real app

React 19 Actions: I Explained 3 Hooks Without Ever Explaining What an Action Is

The word I kept using and never defined

Why any of this needed inventing

<form action={fn}>, and the three things nobody tells you change

Sync Actions exist. They're just not interesting

Client Actions and Server Functions are not the same word twice

The fourth door: useTransition

Where the four actually sit next to each other

The mistake I nearly baked into this whole series

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

The setup

What actually happened

The fix, and what it actually buys you

What this told me that the changelog didn't

Where I'd actually start

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

The setup that made prop drilling look reasonable

Where I put it first, and why it did nothing

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

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

Where I stopped reaching for it

Where useActionState, useOptimistic, and useFormStatus actually sit

I Know the Recipe. I Miss the Winter Kitchen.

Inspiration

Demo

Journey

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

The old trick, and why it quietly lied

What it does, briefly

Combining them: a comment box

Why remounting breaks more than the form

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

The takeaway

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

The habit that felt safe but wasn't

What it actually does

The part that genuinely surprised me

Two more traps I walked straight into

When I don't reach for it

The actual takeaway

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

The setup

The moment I stopped trusting the demo

The fix isn't anything specific to useOptimistic

One comment made me think harder

The rollback question that sent me down a rabbit hole

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

What changed for me

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

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

The fix isn't anything specific to useOptimistic

The rollback question that sent me down a rabbit hole

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

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

Where the rest of this lives

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

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

Bug 2: The Navigation That Never Reached the Proxy

Bug 3: A Database Integer in the JWT Sub Claim

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

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

What Shipped After These Five Bugs Were Gone

Three Things for the Auth Checklist After This Build

Get the Auth Kit

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

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

The gap that looks fine until it isn't

The Data Access Layer: why it exists

The Layout trap that catches everyone once

Roles vs permissions inside actions

What to return from Server Actions

Before you ship

Where this series ends

`<form action={fn}>`, and the three things nobody tells you change