DEV Community: Ahmed Mahmoud

Route Handlers vs Server Actions in Next.js: When I Reach for Each

Ahmed Mahmoud — Tue, 21 Jul 2026 06:14:51 +0000

Headline: In the Next.js App Router, a Server Action is an async function you call directly from a component to run a mutation, and a Route Handler is a standard HTTP endpoint at app/api/**/route.ts. Reach for a Server Action for mutations driven by your own React UI; reach for a Route Handler for public APIs, webhooks, and streaming. Both compile to publicly callable endpoints, so authenticate inside each one.

Key takeaways

A Server Action is an async function marked 'use server' that Next.js exposes as an internal POST endpoint you invoke directly from a component — usually a form action.
A Route Handler is a function exported from app/api/**/route.ts named after an HTTP method that receives a Web Request and returns a Web Response.
Use a Server Action for mutations from your own UI — progressive enhancement plus revalidateTag in the same round trip.
Use a Route Handler for public APIs, webhooks, OAuth callbacks, cacheable GET endpoints, and streaming.
Both are public endpoints — authenticate, authorize, and validate inputs inside every one.

What is a Server Action vs a Route Handler in Next.js?

A Server Action is an async function marked with the 'use server' directive that Next.js compiles into an RPC-style endpoint. You import it and call it like a normal function — most often as the action of a <form> — and Next.js serializes the call over a POST request behind the scenes.

A Route Handler is a function exported from a route.ts file inside app/, named after the HTTP method it serves (GET, POST, PUT, PATCH, DELETE). It receives a standard Web Request and returns a standard Web Response, so you control the status code, headers, and body directly. It replaces pages/api.

When should I use a Server Action instead of a Route Handler?

Use a Server Action when the mutation is triggered from your own React UI and has no external consumer. A form that updates a profile, a button that deletes a row — these belong in Server Actions because the action lives next to the component that calls it.

Server Actions give you progressive enhancement (a <form action={fn}> works before JS hydrates) and in-place cache revalidation (revalidateTag re-renders affected Server Components in the same round trip).

// app/actions.ts
'use server';
import { revalidateTag } from 'next/cache';
import { auth } from '@/lib/auth';

export async function updateName(formData: FormData) {
  const session = await auth();                 // authenticate INSIDE the action
  if (!session) throw new Error('Unauthorized');

  const name = String(formData.get('name') ?? '').trim();
  if (!name) return { error: 'Name is required' };

  await db.user.update({ where: { id: session.userId }, data: { name } });
  revalidateTag('profile');
  return { ok: true };
}

When should I use a Route Handler instead of a Server Action?

Use a Route Handler when something outside your React tree calls the endpoint over a stable URL: webhook receivers (Stripe, GitHub), OAuth callbacks, mobile or third-party API consumers, cron jobs, and cacheable GET endpoints.

Route Handlers are also the only option for raw request access or streaming. A Stripe webhook needs the unparsed body to verify the signature; an SSE feed or LLM token stream returns a ReadableStream. Server Actions return a single serialized value.

// app/api/webhooks/stripe/route.ts
import { headers } from 'next/headers';
import { stripe } from '@/lib/stripe';

export async function POST(req: Request) {
  const body = await req.text();                        // raw body for signature check
  const sig = (await headers()).get('stripe-signature')!;
  let event;
  try {
    event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WH_SECRET!);
  } catch {
    return new Response('Invalid signature', { status: 400 });
  }
  return Response.json({ received: true });
}

How do Route Handlers and Server Actions compare?

Aspect	Server Action	Route Handler
How it's called	Imported and called like a function	HTTP request to a URL
HTTP method	Always POST (internally)	Any (GET/POST/PUT/PATCH/DELETE)
External clients	No stable public contract	Yes — stable URL + method
Progressive enhancement	Yes (form works without JS)	No
Cacheable GET	No	Yes (`Cache-Control`)
Streaming	No	Yes (`ReadableStream`)
Cache revalidation	`revalidateTag` inline	Manual
Best for	Mutations from your own UI	Public APIs, webhooks, streaming

Do I need a Route Handler to fetch data for my own page?

No. Inside a Server Component you query your database directly — no Route Handler required. Wrapping the query in app/api and fetching it from the same server just adds an HTTP round trip and a second cache layer for no benefit.

// app/dashboard/page.tsx — no Route Handler, no fetch()
export default async function Page() {
  const stats = await db.stats.find();
  return <Stats data={stats} />;
}

Reserve Route Handler GETs for data a different client needs: a public JSON API, an edge-cached response, or an endpoint a mobile app calls.

Are Server Actions and Route Handlers both public endpoints?

Yes — both are publicly reachable POST endpoints. A Server Action is not private just because you call it from a component and never see its URL. Next.js compiles each action into an endpoint with an unguessable ID, but that ID can be invoked directly with a crafted request. The action ID is obscurity, not authorization.

Treat every Server Action and Route Handler as an untrusted entry point: authenticate the caller, check authorization, and validate every input inside the function body. The client UI enforces nothing.

FAQ

Q: Can a Server Action handle a GET request?
A: No. Server Actions always execute as POST. For a cacheable GET endpoint, use a Route Handler exporting a GET function.

Q: Should I use a Route Handler to fetch data for my own page?
A: No. In a Server Component, query your data source directly. A Route Handler adds an extra HTTP round trip and cache layer for no benefit.

Q: Are Server Actions secure by default because they have no visible URL?
A: No. Every Server Action compiles to a callable POST endpoint. Authenticate, authorize, and validate inputs inside the action itself.

Q: Which one supports streaming responses?
A: Route Handlers. Return a ReadableStream for SSE or LLM token streams. A Server Action returns one serialized result.

Q: Can a mobile app or third-party service call my Server Actions?
A: Not reliably. Server Action IDs are generated at build time and are not a stable public contract. Expose a Route Handler with a versioned URL.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

URL State in the Next.js App Router: How I Stopped Losing UI State on Refresh

Ahmed Mahmoud — Mon, 20 Jul 2026 13:28:25 +0000

Headline: URL state means storing UI state — filters, active tab, search query, pagination — in the URL query string instead of React useState, so a refresh, a shared link, or the back button restores exactly what the user saw. In the Next.js App Router I read it with useSearchParams() or the async searchParams prop, write it with router.replace(), and reach for nuqs when I want a type-safe, useState-shaped API. The trap that cost me an afternoon: a component calling useSearchParams() must sit inside a React <Suspense> boundary or the production build fails.

A dashboard I built kept its filter panel in useState. Users would filter to a subset, refresh to pull fresh data, and lose every selection. The fix was not more state management — it was less: move the state a user expects to survive a reload into the URL, where the browser persists it for free.

Key takeaways

URL state stores UI state in the URL query string, so a refresh, a shared link, or the back button restores what the user saw; useState is lost on every reload.
Read query state with useSearchParams() in a client component, or the async searchParams prop on a server component (a Promise you await in Next.js 15).
Write it with router.replace() and a URLSearchParams object; use replace not push so filter tweaks do not flood the back-button history.
The nuqs library gives a useState-shaped hook, useQueryState, with typed parsers like parseAsInteger instead of raw strings.
A component calling useSearchParams() must be wrapped in <Suspense> during static rendering, or the Next.js build errors.

When should I store state in the URL instead of useState?

Store state in the URL when the user expects it to survive a refresh, a shared link, or a bookmark — filters, the active tab, a search term, sort order, and pagination all qualify. Keep state in useState when it is ephemeral: a hover state, whether a dropdown is open, an unsaved form draft. My test is one question: if the user copies this URL and sends it to a colleague, should the colleague see the same view? If yes, it belongs in the URL. URL state also kills a class of sync bugs — there is one source of truth, the query string, instead of a useState value that drifts from the address bar.

How do I read search params in the Next.js App Router?

In a client component, call useSearchParams() from next/navigation, which returns a read-only URLSearchParams.

'use client';
import { useSearchParams } from 'next/navigation';

function StatusBadge() {
  const searchParams = useSearchParams();
  const status = searchParams.get('status') ?? 'all';
  return <span>{status}</span>;
}

In a server component, skip the hook and read the searchParams prop. In Next.js 15 it is a Promise, so you await it and fetch the correct data before rendering.

export default async function Page({
  searchParams,
}: {
  searchParams: Promise<{ status?: string }>;
}) {
  const { status = 'all' } = await searchParams;
  const rows = await getRows(status);
  return <Table rows={rows} />;
}

How do I write to the URL without triggering a full navigation?

Build a fresh URLSearchParams from the current params, set your key, and call router.replace(). Seeding from the existing params preserves every other query key.

'use client';
import { useRouter, usePathname, useSearchParams } from 'next/navigation';

function StatusFilter() {
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();

  function setStatus(value: string) {
    const params = new URLSearchParams(searchParams);
    params.set('status', value);
    router.replace(`${pathname}?${params.toString()}`);
  }

  return (
    <select onChange={(e) => setStatus(e.target.value)}>
      <option value="all">All</option>
      <option value="open">Open</option>
    </select>
  );
}

Use router.replace(), not router.push(). push adds a history entry per change, so the back button steps through each tweak; replace keeps one entry.

What is nuqs, and what does useQueryState add?

nuqs is a type-safe search-params state manager for React that turns the read-plus-router.replace dance into one useState-shaped hook. useQueryState(key, parser) returns a [value, setValue] tuple, but the value lives in the URL.

'use client';
import { useQueryState, parseAsInteger } from 'nuqs';

function ProductSearch() {
  const [query, setQuery] = useQueryState('q', { defaultValue: '' });
  const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));

  return (
    <input value={query} onChange={(e) => setQuery(e.target.value || null)} />
  );
}

The parsers are the win: parseAsInteger, parseAsBoolean, parseAsArrayOf, parseAsStringEnum, and parseAsIsoDateTime convert the URL string into the type your component wants and back on write. Setting a value to null clears the key. In nuqs v2 you wrap the app once in <NuqsAdapter> from nuqs/adapters/next/app, and batch several keys with useQueryStates.

Native searchParams or nuqs — which should I pick?

Concern	Native useSearchParams	nuqs
Types	Strings only, parse yourself	Typed parsers (int, bool, array, enum, date)
Setup	None	`<NuqsAdapter>` wrapper once
Write API	Manual `URLSearchParams` + `router.replace`	`useState`-like tuple
Many keys	Hand-built query string	`useQueryStates` batches them
Defaults	Manual `?? fallback`	`withDefault` + `clearOnDefault`
Rapid writes	Debounce yourself	Built-in throttling

What breaks — Suspense, throttling, and stale server data?

The build aborts with "useSearchParams() should be wrapped in a suspense boundary". During static rendering, any component reading useSearchParams() must sit inside a <Suspense> boundary, because the params are only known at request time.

import { Suspense } from 'react';

<Suspense fallback={<FiltersSkeleton />}>
  <StatusFilter />
</Suspense>

Two more edges. Writing to the URL on every keystroke spams history and re-renders — nuqs throttles by default and exposes throttleMs; with native code you debounce yourself. And whether a URL change re-runs server components depends on shallow routing: nuqs defaults to shallow: true (client-only URL update), so set shallow: false when a server component filters through the searchParams prop and needs the new value.

FAQ

Q: When should I keep state in the URL versus useState?
A: URL for state that should survive a refresh, shared link, or bookmark — filters, tabs, search, sort, pagination. useState for ephemeral UI like open menus, hover, or an unsaved form draft.

Q: Do I need nuqs, or is useSearchParams enough?
A: useSearchParams plus router.replace covers reading and writing. nuqs adds typed parsers, a useState-like API, multi-key batching, and throttling. One or two string params: native. Many typed params: nuqs.

Q: Why does my build fail with "useSearchParams() should be wrapped in a suspense boundary"?
A: During static rendering Next.js requires any component calling useSearchParams() to be inside a <Suspense> boundary, since the value is only known at request time. Wrap that component.

Q: Should I use router.push or router.replace for filter changes?
A: router.replace. push adds a history entry per change, so the back button walks through every tweak; replace keeps one entry.

Q: Does updating the URL re-run my server components?
A: With native router.replace, yes. With nuqs it depends on the shallow option: default shallow: true is client-only, shallow: false triggers the server refetch.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Error Handling in the Next.js App Router: How I Stopped One Throw From Blanking the Page

Ahmed Mahmoud — Sun, 19 Jul 2026 15:48:47 +0000

Headline: In the Next.js App Router, error.tsx is a React error boundary for a route segment: it catches errors thrown while rendering that segment and everything nested below it, hands you an error object and a reset() function, and must be a Client Component. It does not catch errors in its own layout, in event handlers, or in async code that runs outside render.

I lost an afternoon to a single unhandled throw that blanked an entire dashboard. One failing data call in a nested component took down the whole page instead of the one panel that broke. The App Router already had the tools to contain it — I just had the wrong mental model of where each error file sits and what it actually catches.

Key takeaways

An error.tsx file in a route segment creates a React error boundary that catches errors thrown during rendering of that segment's page and any nested layouts, pages, and components below it.
error.tsx must start with 'use client' because React error boundaries rely on class-component lifecycle methods that only run in the browser; the file receives two props, error and reset.
error.tsx cannot catch an error thrown by the layout in its own segment — that layout renders above the boundary, so you place an error.tsx in the parent segment to catch it.
global-error.tsx is the only boundary that catches errors in the root layout; it replaces the root layout when active, so it must render its own <html> and <body>, and it runs only in production.
In production, Next.js strips the message from server-side errors and replaces it with a digest hash so nothing leaks to the browser; the original error is logged on the server.

What does error.tsx actually catch in the App Router?

An error.tsx file catches errors thrown while rendering the route segment it lives in and everything nested below it. Drop it in a segment folder and Next.js automatically wraps that segment's page.tsx, its nested layouts and pages, and every Server and Client Component they render in a React error boundary.

What it does not catch is the part that trips people up: errors thrown in event handlers like onClick, errors thrown in async code that runs after render, a notFound() call, and — the one that cost me time — an error thrown by the layout.tsx or template.tsx in the same segment.

// app/dashboard/error.tsx catches throws from
// app/dashboard/page.tsx and anything nested under /dashboard,
// but NOT from app/dashboard/layout.tsx.

Why must error.tsx be a Client Component?

error.tsx must be a Client Component because React error boundaries are implemented with class-component lifecycle methods — getDerivedStateFromError and componentDidCatch — that only execute in the browser. It receives exactly two props: error, an Error instance that may carry a digest string, and reset, a zero-argument function that re-renders the boundary.

'use client';

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <div role="alert">
      <h2>Something went wrong</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}

When do I need global-error.tsx instead of error.tsx?

You need global-error.tsx when the error happens in the root layout or root template, which sit above every ordinary error.tsx. A regular error.tsx renders inside the layout it protects, so it can never replace a broken root layout. global-error.tsx replaces the entire root layout when triggered — which is why it must include its own <html> and <body> tags. It is active only in production; in development the Next.js error overlay takes over.

'use client';

export default function GlobalError({ error, reset }) {
  return (
    <html>
      <body>
        <h2>Application error</h2>
        <button onClick={() => reset()}>Reload</button>
      </body>
    </html>
  );
}

How do I handle "not found" separately from errors?

Call notFound() from next/navigation, which throws a dedicated control-flow error caught by the nearest not-found.tsx, not by error.tsx. A missing record is an expected outcome, not a crash, so it deserves its own boundary and a real HTTP 404.

import { notFound } from 'next/navigation';

export default async function Page({ params }) {
  const post = await getPost(params.slug);
  if (!post) notFound(); // renders the nearest not-found.tsx, sends HTTP 404
  return <Article post={post} />;
}

Why are my server error messages replaced with a digest in production?

Next.js deliberately strips the message and stack from errors thrown on the server in production and replaces them with a digest property — an auto-generated hash — so it never leaks internals or secrets to the browser. The full error is logged on the server, and the digest is what lets you match a user's report to that server log. In development you still see the real message. So inside a production error.tsx, error.message for a server error is generic — build your correlation around error.digest.

How do I recover without a reload — and what about event-handler errors?

Call the reset() prop to recover without a full page reload; it asks React to re-render the boundary's contents by re-attempting the failed segment. If the cause was transient, the segment comes back with no navigation. For errors error.tsx never sees — event handlers and async callbacks — catch them yourself and drive the UI with state.

'use client';
import { useState } from 'react';

function SaveButton() {
  const [err, setErr] = useState<string>();
  async function onClick() {
    try {
      await save();            // a rejection here is NOT caught by error.tsx
    } catch {
      setErr('Save failed');   // surface it with local state instead
    }
  }
  return (
    <>
      {err && <p role="alert">{err}</p>}
      <button onClick={onClick}>Save</button>
    </>
  );
}

For expected failures in a Server Action, I return a typed error value rather than throwing, so the form renders the message inline without tripping an error boundary.

The App Router error files at a glance

File	What it catches	Client Component?	Notes
`error.tsx`	Render errors in its segment and nested children	Yes	Not its own layout; receives `error` + `reset`
`global-error.tsx`	Errors in the root layout or template	Yes	Replaces the root layout; must render `<html>`/`<body>`; production only
`not-found.tsx`	`notFound()` calls and unmatched routes	No	Returns HTTP 404; not triggered by real crashes
Event handlers / async	None of the above	n/a	Use `try/catch` and surface with state

FAQ

Q: Does error.tsx catch errors in its own layout.tsx?
A: No. The layout renders above the boundary. To catch an error thrown by a segment's layout, put an error.tsx in the parent segment.

Q: Why does my error.tsx not appear in development?
A: Next.js shows its development error overlay on top of your boundary, and global-error.tsx only takes over in a production build.

Q: Do error boundaries catch errors in onClick handlers?
A: No. React error boundaries only catch errors thrown during rendering. Wrap event-handler and async logic in try/catch and surface the failure with state.

Q: What is the digest property on the error object?
A: A hash Next.js generates for server-side errors in production, replacing the real message so nothing leaks to the client. Match it against your server logs.

Q: Does calling notFound() trigger error.tsx?
A: No. notFound() throws a dedicated control-flow signal caught by the nearest not-found.tsx and returns a 404. error.tsx is only for unexpected exceptions.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

View Transitions in Next.js: How I Added Animated Page Changes Without a Library

Ahmed Mahmoud — Sat, 18 Jul 2026 07:23:35 +0000

Headline: The View Transitions API animates the change between two DOM states — you call document.startViewTransition(), and the browser cross-fades or morphs the old page into the new one. In a Next.js App Router app I added smooth page and element transitions with a few lines of CSS and no animation library, and the only real trap was giving two elements the same view-transition-name.

Key takeaways

The View Transitions API animates between two DOM states via document.startViewTransition(updateDOM); the browser snapshots the page before and after your callback and animates the difference.
The default transition is a full-page cross-fade named root; assign view-transition-name to any element to animate it independently.
For Next.js App Router client navigations, wrap router.push in document.startViewTransition, or set experimental.viewTransition to use React's <ViewTransition> component.
React's <ViewTransition> is still experimental in React 19.x — opt-in behind a flag, not stable.
A duplicate view-transition-name in one snapshot makes the browser skip the transition; every name must be unique per snapshot.

What is the View Transitions API, and what problem does it solve?

The View Transitions API is a browser API that animates the visual change between two states of the DOM. Before it, animating a route change meant keeping both the old and new UI in the DOM at once, coordinating CSS classes, and cleaning up after — a library's whole job. The API replaces that: you call document.startViewTransition(callback), the browser screenshots the current page, runs your callback to update the DOM, screenshots the new state, and cross-fades between the two snapshots. Same-document (SPA) transitions shipped in Chrome 111 in March 2023; cross-document (MPA) navigations shipped in Chrome 126 in June 2024, and Firefox and Safari have since added the same-document API.

How do I run my first view transition?

Call document.startViewTransition() with a callback that mutates the DOM. The default animation is a quarter-second cross-fade of the whole page.

function update() {
  document.body.dataset.theme = 'dark';
}

if (document.startViewTransition) {
  document.startViewTransition(update); // animated
} else {
  update();                              // fallback: no animation
}

Feature-detect first — document.startViewTransition is undefined without support, and calling the update directly is the correct fallback. The method returns a ViewTransition object with three promises: .updateCallbackDone, .ready, and .finished. Await .finished to run code after the transition.

How do I animate one element independently?

Give the element a unique view-transition-name and the browser animates it as its own group instead of folding it into the page cross-fade — this is the shared-element effect where a thumbnail grows into a hero image.

.hero-image { view-transition-name: hero; }

::view-transition-old(hero),
::view-transition-new(hero) { animation-duration: 0.4s; }

During a transition the browser builds pseudo-elements: ::view-transition-old(hero) is the outgoing snapshot, ::view-transition-new(hero) the incoming one, and ::view-transition-group(hero) wraps both and animates position and size. The name root is assigned to the whole document, so ::view-transition-old(root) targets the full-page cross-fade.

How do I add view transitions to Next.js App Router navigation?

Wrap the navigation in document.startViewTransition so the DOM update React performs during the route change becomes the transition's callback.

'use client';
import { useRouter } from 'next/navigation';

export function useViewTransitionRouter() {
  const router = useRouter();
  return (href: string) => {
    if (!document.startViewTransition) return router.push(href);
    document.startViewTransition(() => router.push(href));
  };
}

For cross-document transitions in a static or MPA-style site, skip JavaScript and opt in with CSS in both pages:

@view-transition { navigation: auto; }

The community next-view-transitions package wraps the client pattern if you would rather not write the hook.

What is React's `<ViewTransition>` component, and is it ready?

<ViewTransition> is an experimental React component that animates its children when they enter, exit, or reorder from a transition or a resolving Suspense boundary. Instead of calling document.startViewTransition yourself, you wrap the changing UI and React drives the API.

import { unstable_ViewTransition as ViewTransition } from 'react';

<ViewTransition>
  <ProductList items={items} />
</ViewTransition>

It is still experimental in React 19.x — the import is prefixed unstable_, and in Next.js you enable it with experimental.viewTransition: true. I ship the plain document.startViewTransition approach in production because it is a stable browser API, and keep <ViewTransition> for prototypes.

What breaks — duplicate names, reduced motion, and performance?

The failure I hit most: two elements sharing one view-transition-name in the same snapshot. The browser cannot decide which to morph, so it skips the transition and logs a warning. For a list, name only the item that is actually transitioning, using a unique id.

Problem	Cause	Fix
Transition doesn't animate	duplicate `view-transition-name` in one snapshot	make each name unique per snapshot
Motion for users who opted out	API always animates	disable animation inside `prefers-reduced-motion: reduce`
Dropped frames on low-end devices	large full-screen snapshots	limit named transitions to elements that must move

@media (prefers-reduced-motion: reduce) {
  ::view-transition-group(*),
  ::view-transition-old(*),
  ::view-transition-new(*) { animation: none !important; }
}

The old and new states render as snapshots and the group moves them with transforms, which the compositor handles cheaply — but keep independently-named transitions to the elements that genuinely need to move.

FAQ

Q: Which browsers support the View Transitions API?
A: Same-document transitions shipped in Chrome 111 (March 2023) and are now in Firefox and Safari; cross-document transitions shipped in Chrome 126 (June 2024). Always feature-detect document.startViewTransition.

Q: Do I need a library for view transitions in Next.js?
A: No. Wrapping router.push in document.startViewTransition covers client navigations with no dependency. next-view-transitions just packages that pattern.

Q: Why did my view transition not animate?
A: Usually two elements share the same view-transition-name in one snapshot, which makes the browser skip the transition. Names must be unique per captured state.

Q: Is React's <ViewTransition> component stable?
A: No. As of React 19.x it is experimental, imported as unstable_ViewTransition and enabled behind experimental.viewTransition. Use the browser API directly in production.

Q: Can view transitions animate width and height?
A: Yes, via ::view-transition-group, which animates size and position between snapshots. Keep heavier animation to transform and opacity, since the old and new states are rendered as images.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Debugging Hydration Mismatches in the Next.js App Router

Ahmed Mahmoud — Thu, 16 Jul 2026 10:18:10 +0000

Headline: A hydration mismatch happens when the HTML your Next.js server renders does not match what React produces on the first client render, so React 19 throws away that subtree and re-renders it in the browser — you see a flash and a console diff. The fix is almost never suppressHydrationWarning; it is making the first client render deterministic.

Key takeaways

A hydration mismatch is when the HTML Next.js renders on the server does not match React's first client render, so React 19 discards that subtree and re-renders it in the browser.
The usual causes are non-deterministic values (Date.now(), Math.random()), browser-only APIs (localStorage, window) read during render, invalid HTML nesting, and DOM changes injected by browser extensions.
suppressHydrationWarning is not a general fix; it silences the warning for one element whose text is legitimately allowed to differ, like a timestamp.
Render browser-only values with a mounted flag and useEffect, or with useSyncExternalStore and a server snapshot, so both sides agree.
A hydration mismatch appears only on the first server-rendered load, never on client-side navigation in the App Router.

I lost the better part of an afternoon to a single flash on refresh: a timestamp column flickered and the theme toggle blinked to its default for one frame, and the console held one red line — a hydration mismatch. Once it clicked that hydration is React re-attaching to server HTML rather than re-rendering it, the whole family of bugs turned mechanical. These are my field notes from the App Router.

What is a hydration mismatch, and why does it break the page?

A hydration mismatch is when the HTML Next.js renders on the server does not match the output of React's first render in the browser. During hydration, React walks the existing server DOM and attaches event listeners to it instead of recreating it, assuming the tree it computes matches the DOM already on the page. When the two differ, React 19 discards the mismatched subtree and re-renders it from scratch on the client. That re-render is the flash you see, and it forfeits the server-rendering benefit for that subtree. In development, React 19 prints a readable diff naming the element and the differing text, a large improvement over the old generic message.

Why do `Date.now()` and `localStorage` cause a hydration error?

Reading a non-deterministic or browser-only value during render is the most common cause. Date.now(), Math.random(), and new Date().toLocaleString() produce different output on the server than in the browser, because the server ran a moment earlier and in a different timezone and locale. Reading localStorage, window, or navigator during render is worse: the server has no such object, so it renders one branch and the client renders another.

// server and client compute different text -> mismatch
function LastSeen() {
  return <span>{new Date().toLocaleTimeString()}</span>;
}

The server stamps the time it rendered; the browser stamps a later time in the user's locale. React sees two different strings and throws.

When should I use `suppressHydrationWarning`?

Reach for suppressHydrationWarning only when the text of a single element is legitimately allowed to differ between server and client; a timestamp is the canonical case. It suppresses the warning for that one element, one level deep. It does not silence its children, and it is not a blanket fix.

<time suppressHydrationWarning>{new Date().toLocaleTimeString()}</time>

Using it to hide a real logic mismatch just trades a visible error for an invisible one. If you find yourself adding it to more than a couple of leaf nodes, the real problem is elsewhere.

How do I render a client-only value without a mismatch?

Render a stable placeholder on the server and swap in the real value after mount. For a theme, a viewport width, or a localStorage preference, the two-pass pattern uses a mounted flag:

function Theme() {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);
  if (!mounted) return <ThemeSkeleton />; // same markup on server + first client render
  return <ThemeToggle value={localStorage.getItem('theme')} />;
}

Both the server and the first client render return the skeleton, so they match; the real value appears on the second render. For external browser state, useSyncExternalStore is cleaner because its third argument is a server snapshot:

const isWide = useSyncExternalStore(
  subscribe,
  () => window.matchMedia('(min-width: 1024px)').matches, // client
  () => false                                            // server snapshot
);

Supplying that server value is what keeps hydration consistent. For a component that can never render on the server, next/dynamic with ssr: false skips server rendering entirely.

Why do browser extensions cause hydration errors on `<body>`?

Browser extensions cause hydration errors by mutating the DOM before React hydrates. Grammarly injects data-gramm attributes, password managers add wrappers, and dark-mode extensions rewrite inline styles on <html> and <body>. The server sent clean markup; by the time React hydrates, the DOM carries extra attributes, so they mismatch. Because you cannot control the user's extensions, the accepted fix is suppressHydrationWarning on the <html> and <body> elements in your root layout, which the Next.js documentation recommends. It is safe there because those elements carry no dynamic text of your own to protect.

How do I fix invalid HTML nesting mismatches?

Invalid HTML nesting causes mismatches that look mysterious because your JSX seems fine. The browser silently repairs illegal nesting by moving or closing tags, so the DOM it built no longer matches the tree React expects, and React reports a mismatch on an element you never touched.

Invalid nesting	Why the browser rewrites it	Fix
`<div>` inside `<p>`	the `<p>` auto-closes before a block element	use a `<div>` or `<span>` wrapper
`<p>` inside `<p>`	a nested `<p>` is not allowed, so the outer closes early	flatten to a single `<p>`
`<a>` inside `<a>`	interactive elements cannot nest	restructure so links are siblings
`<table>` without `<tbody>`	the browser inserts a `<tbody>` for you	add the `<tbody>` yourself

The fix is always to make the JSX produce valid HTML. React 19's diff usually points at the reparented node, which is the fastest way to find it.

FAQ

Q: What is the difference between a hydration mismatch and a rendering error?
A: A hydration mismatch is specifically the server HTML disagreeing with the first client render, and it appears only on initial load, never on client-side navigation. A rendering error is any exception thrown while rendering, at any time.

Q: Does suppressHydrationWarning fix the flash?
A: No. It silences the console warning for one element, but React still re-renders the mismatched content on the client. Use it only when the difference is intentional, like a timestamp.

Q: Why does the error only happen on refresh and not when I navigate?
A: Hydration runs once, on the first server-rendered load. Client-side navigation in the App Router renders entirely in the browser, so there is no server HTML to mismatch against.

Q: Can useEffect cause a hydration mismatch?
A: No. useEffect runs after hydration, so state you set inside it cannot affect the first render React compares against the server HTML. That is why the mounted-flag pattern is safe.

Q: How do I find which component is mismatching?
A: Read the React 19 development console diff, which names the element and shows the differing text. If you suspect an extension, reproduce in an incognito window with extensions disabled.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Fixing INP: Field Notes on Interaction to Next Paint in a React App

Ahmed Mahmoud — Thu, 16 Jul 2026 06:04:51 +0000

Headline: Interaction to Next Paint (INP) is the Core Web Vitals metric that measures how long your page takes to visually respond to a user interaction, and since March 2024 it replaced First Input Delay (FID). When my dashboard felt sluggish on every click, the fix was not a faster server — it was getting React off the main thread across the three phases of each interaction.

I spent the better part of a week chasing a "the app feels slow" complaint that no server metric explained. The API was fast, Lighthouse scored green in the lab, but every click on the filter panel lagged before anything changed on screen. The culprit was INP, and splitting each interaction into three phases made the fixes small and mechanical.

Key takeaways

INP (Interaction to Next Paint) measures the latency from a user interaction to the next frame the browser paints; 200 ms or less is good, over 500 ms is poor, both at the 75th percentile.
INP replaced First Input Delay (FID) as a Core Web Vital in March 2024 — FID measured only the first interaction's input delay; INP measures the full response of nearly every interaction.
Every interaction has three phases: input delay, processing time, presentation delay. Fix the one that dominates.
The two highest-leverage React fixes are startTransition for non-urgent updates and scheduler.yield() for long tasks.
INP is a field metric — measure it with the web-vitals library, not Lighthouse.

What is INP and how is it different from FID?

INP reports the longest interaction latency a user experiences on a page, from click, tap, or keypress until the next painted frame. Google promoted INP to a core metric in March 2024, retiring FID. FID measured only the input delay of the first interaction and ignored everything after the handler started. INP measures the whole interaction — input delay plus handler work plus rendering — and reports the worst one across the session. A page can post a perfect FID and still feel broken.

What are the three phases of an interaction?

Input delay: action until the event handler starts, usually waiting on a busy main thread.
Processing time: how long your handlers run, including React state updates.
Presentation delay: end of processing until the next paint, dominated by layout and paint.

Record an interaction in the Chrome DevTools Performance panel and it labels all three. Optimize the one that is actually long.

How do I fix input delay?

Input delay is almost always a long task — any JavaScript block occupying the main thread for over 50 ms — blocking the click. Break long tasks into chunks and yield between them with scheduler.yield():

async function processRows(rows) {
  for (const chunk of chunkOf(rows, 50)) {
    renderChunk(chunk);
    await scheduler.yield(); // hand the main thread back so a queued click runs
  }
}

It resumes after the browser handles higher-priority work like input. My biggest win was deferring a third-party analytics init with requestIdleCallback so it stopped blocking first clicks.

How do I fix processing time?

startTransition marks a React state update as non-urgent so React can interrupt it and keep the interaction responsive:

function onChange(e) {
  setQuery(e.target.value);                      // urgent: keep the input live
  startTransition(() => {
    setResults(filter(items, e.target.value));   // non-urgent: interruptible
  });
}

useDeferredValue does the same for a value you receive. Neither is faster — both are interruptible, which is what INP measures. For heavy computation, move it to a Web Worker.

How do I fix presentation delay?

Presentation delay is rendering work on too much DOM. content-visibility: auto skips off-screen elements until they scroll near the viewport:

.list-row {
  content-visibility: auto;
  contain-intrinsic-size: auto 48px; /* reserve height so the scrollbar stays stable */
}

The other cause is layout thrashing — reading offsetHeight then writing a style in the same loop. Batch reads, then writes. For long lists, virtualization beats any CSS trick.

How do I measure INP in the field?

INP is a field metric, so Lighthouse's lab number is only an estimate — it cannot click your buttons. Capture the real one with web-vitals:

import { onINP } from 'web-vitals';

onINP((metric) => {
  navigator.sendBeacon('/vitals', JSON.stringify(metric));
});

The attribution build names the slow element and phase, and Chrome's CrUX field data confirms whether the 75th-percentile score actually moved.

FAQ

Q: What is a good INP score?
A: 200 ms or less at the 75th percentile is good, 200–500 ms needs improvement, over 500 ms is poor.

Q: Is INP a Core Web Vital?
A: Yes — it replaced First Input Delay in March 2024.

Q: Does startTransition make my code faster?
A: No. It marks an update non-urgent so React can interrupt it; the work takes the same time but stops blocking the interaction.

Q: Can I measure INP in Lighthouse?
A: Not reliably. Use the web-vitals library or Chrome's CrUX field data.

Q: What is scheduler.yield()?
A: A browser API that pauses a long task and resumes it after higher-priority work like input, keeping input delay low.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Next.js Server Actions Are Public Endpoints: How I Lock Them Down

Ahmed Mahmoud — Mon, 13 Jul 2026 03:38:53 +0000

Headline: Every Next.js Server Action is a public HTTP endpoint. "use server" marks a function to be called over the network—not protected from the network.

I shipped a feature last quarter that let users export their data. The export logic lived in a Server Action. Three weeks later I realized anyone with a browser console could call that action directly—no session, no auth check—because I forgot to verify the session inside the action itself.

This post is what I learned hardening Server Actions at scale.

Why Server Actions Are Different

Traditional APIs have a clear boundary: your route handlers live in app/api/ and you consciously design them as public endpoints. Server Actions blur that line. You write them inline, they feel like private functions, but Next.js exposes each one as a POST endpoint at a URL derived from a build-time hash.

# What actually happens under the hood
POST /_next/action/abc123def456
Content-Type: application/x-www-form-urlencoded

[encrypted action arguments]

The arguments are encrypted, but the endpoint exists. If your action doesn't check auth, an attacker who finds the action ID can call it.

The Mistakes I See Most

1. Assuming `"use server"` Means Private

// ❌ This is a public HTTP endpoint
"use server"

export async function exportUserData(userId: string) {
  // No auth check — anyone can call this
  return db.query('SELECT * FROM users WHERE id = $1', [userId]);
}

The action is exposed. The arguments aren't, but the endpoint is.

2. Missing Session Checks Inside Actions

// ✅ Check session inside the action itself
"use server"

import { auth } from '@/lib/auth';

export async function exportUserData(userId: string) {
  const session = await auth();
  if (!session?.user?.id) throw new Error('Unauthorized');
  if (session.user.id !== userId) throw new Error('Forbidden');

  return db.query('SELECT * FROM users WHERE id = $1', [userId]);
}

3. Trusting Client-Provided Values Without Validation

Server Actions receive arguments from the client. Even with encryption, you control what your client sends. Validate everything:

// ✅ Validate inputs with Zod
import { z } from 'zod';

const ExportSchema = z.object({
  userId: z.string().uuid(),
  format: z.enum(['csv', 'json']),
});

export async function exportUserData(input: unknown) {
  const session = await auth();
  if (!session) throw new Error('Unauthorized');

  const { userId, format } = ExportSchema.parse(input);
  if (userId !== session.user.id) throw new Error('Forbidden');

  return generateExport(userId, format);
}

The Pattern I Now Use Everywhere

I've settled on a wrapper that enforces auth before any action runs:

// lib/safe-action.ts
import { auth } from '@/lib/auth';
import type { Session } from 'next-auth';

type AuthenticatedAction<T, R> = (session: Session, input: T) => Promise<R>;

export function requireAuth<T, R>(action: AuthenticatedAction<T, R>) {
  return async (input: T): Promise<R> => {
    const session = await auth();
    if (!session?.user) throw new Error('Authentication required');
    return action(session, input);
  };
}

// Usage
export const exportUserData = requireAuth(async (session, input: unknown) => {
  const { userId, format } = ExportSchema.parse(input);
  if (userId !== session.user.id) throw new Error('Forbidden');
  return generateExport(userId, format);
});

This makes the auth requirement impossible to forget—you can't write the action without thinking about the session.

Rate Limiting and Abuse Prevention

Because actions are HTTP endpoints, they're vulnerable to abuse. Add rate limiting at the middleware level:

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';
import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, '10s'),
});

export async function middleware(req: NextRequest) {
  if (req.nextUrl.pathname.startsWith('/_next/action/')) {
    const ip = req.ip ?? '127.0.0.1';
    const { success } = await ratelimit.limit(ip);
    if (!success) return new NextResponse('Too many requests', { status: 429 });
  }
  return NextResponse.next();
}

What I Recommend Auditing Now

Search your codebase for "use server" files. List every exported function.
Check each one for: session verification, input validation, authorization (not just authentication).
Add the requireAuth wrapper (or equivalent) to every action that touches user data.
Add rate limiting at middleware for action endpoints.
Log action calls with user ID and input shape—not full values—so you have an audit trail.

Server Actions are a great DX improvement. They're also a new attack surface if you treat them as private functions when they're actually public endpoints.

Originally published on devya.dev. Also at eng-ahmed.com.

React Compiler in 2026: What It Actually Memoizes (And What It Doesn't)

Ahmed Mahmoud — Sun, 12 Jul 2026 00:18:56 +0000

Headline: React Compiler â€” formerly React Forget â€” shipped stable with React 19 and automatically memoizes components, hooks, and callbacks by analyzing data flow at build time. No dependency arrays to write; the compiler infers them. Here is what it handles, when it opts out, and whether you should delete your useMemo calls.

Key takeaways

React Compiler inserts useMemo, useCallback, and React.memo automatically at build time â€” no dependency arrays to maintain.
Enable it in Next.js 15/16 with experimental.reactCompiler: true in next.config.ts.
The compiler is conservative: if it cannot prove memoization is safe, it emits the component unchanged.
"use no memo" is the escape hatch for functions the compiler should not touch.
Run npx react-compiler-healthcheck@latest before enabling to see coverage and violations.

What does React Compiler actually do?

React Compiler transforms component and hook code at build time to insert memoization automatically. Instead of useMemo(() => expensiveCalc(a, b), [a, b]), the compiler analyzes data flow, determines which values are stable across renders, and emits equivalent memoized code. The compiled output uses React's memo infrastructure at runtime. The compiler is babel-plugin-react-compiler â€” it works with any Babel-based build pipeline.

How do I enable it in Next.js?

// next.config.ts
const nextConfig = {
  experimental: {
    reactCompiler: true,
  },
};
export default nextConfig;

Before enabling, run the healthcheck:

npx react-compiler-healthcheck@latest

The healthcheck reports optimizable component count, files with violations, and blocking patterns. Fix violations first for more coverage on day one.

What does the compiler memoize?

Components â€” equivalent to React.memo; re-renders only when props change.
Values â€” equivalent to useMemo; computed results, derived arrays, objects.
Callbacks â€” equivalent to useCallback: event handlers, functions passed as props.

Dependencies are inferred from escape analysis â€” no dependency array needed.

When does it opt out?

The compiler skips a function and emits it unchanged when:

Props/state mutated directly â€” props.items.push(x) violates React rules; compiler detects and opts out.
Mutable external references read â€” a singleton the compiler cannot prove is stable.
Rules of Hooks violated â€” hooks called conditionally cause the whole file to be skipped.
Complex let reassignment â€” non-obvious variable flows the compiler cannot track.

The `"use no memo"` escape hatch

function MyComponent({ data }: { data: unknown }) {
  "use no memo";
  return <div>{JSON.stringify(data)}</div>;
}

Use when compiler output is wrong for a specific function or you are wrapping a library relying on reference instability. Intentionally verbose â€” should feel deliberate.

Should I delete useMemo and useCallback?

For components the compiler handles: yes, eventually. The healthcheck shows which are optimized â€” those are safe to clean up. Keep manual memoization for non-optimizable components, useMemo as a semantic signal for expensive computations, and third-party components you cannot change.

Manual vs compiler memoization

Dimension	Manual hooks	React Compiler
Dependency arrays	You write them	Compiler infers
Stale closure risk	Real â€” wrong deps cause bugs	Eliminated
Coverage	Only annotated values	All optimizable code
Escape hatch	Remove the hook call	`"use no memo"`

FAQ

Q: Does it work without Next.js?

A: Yes â€” babel-plugin-react-compiler works with Vite, webpack, or any Babel pipeline. Next.js's experimental.reactCompiler is a convenience wrapper.

Q: Will it break existing components?

A: No â€” it only memoizes what it can prove is correct and leaves everything else unchanged. Run the healthcheck first.

Q: Does it replace React.memo?

A: For fully analyzable components, yes. React.memo on compiler-skipped components still adds value.

Q: Can I enable gradually?

A: Yes â€” pass an includes filter to babel-plugin-react-compiler to target specific directories.

Q: What React version is required?

A: React 19+. Does not work on React 18.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Partial Prerendering in Next.js: The Static Shell + Dynamic Stream Model

Ahmed Mahmoud — Sun, 12 Jul 2026 00:16:41 +0000

Headline: Partial Prerendering (PPR) in Next.js serves a static HTML shell from the CDN edge instantly, then streams Suspense-wrapped dynamic children from the origin in the same HTTP response. No full-page ISR staleness, no full-page origin latency. I shipped it on two production routes â€” here is the model.

Key takeaways

PPR serves a static HTML shell from the CDN edge, then streams dynamic Suspense children from the origin in the same response.
The static shell is built at build time â€” outside <Suspense> renders statically; inside renders dynamically per request.
PPR replaces the ISR vs. dynamic tradeoff for pages that are mostly static with isolated personalized sections.
No changes to Server Components or Suspense â€” just experimental.ppr: 'incremental' in config and export const experimental_ppr = true per route.
PPR and use cache are complementary: CDN delivery for the shell, origin memoization for dynamic islands.

What does PPR actually do?

PPR splits a page into two rendering phases within the same HTTP response. At build time, Next.js freezes everything that does not read dynamic request data into a static HTML shell on the CDN edge. At request time, the CDN delivers the shell at edge latency while the origin streams each <Suspense> boundary's content into the same response.

On a product page: navigation, title, and description arrive at CDN speed. The in-stock badge and personalized recommendations stream from the origin a fraction of a second later. The user sees a nearly-complete page immediately.

How is PPR different from ISR and streaming Suspense?

Strategy	First byte	Dynamic freshness	Staleness
ISR (revalidate: N)	CDN edge	Whole page up to N seconds stale	Full page
Dynamic rendering	Origin	100% fresh; waits for slowest query	None
Streaming Suspense (no PPR)	Origin	Fresh; TTFB includes origin latency	None
PPR	CDN edge	Dynamic islands 100% fresh	Static shell only

How do I enable PPR?

// next.config.ts
export default { experimental: { ppr: 'incremental' } };

// app/products/[slug]/page.tsx
export const experimental_ppr = true;

export default async function ProductPage({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  return (
    <main>
      <ProductHeader slug={slug} />          {/* static shell â€” CDN */}
      <Suspense fallback={<StockSkeleton />}>
        <StockAvailability slug={slug} />    {/* dynamic â€” origin */}
      </Suspense>
    </main>
  );
}

Anything outside <Suspense> must not read dynamic data. If it calls cookies(), the build fails with a clear error.

What belongs in the shell vs. inside Suspense?

Static shell: navigation, footer, static content, layout structure, images independent of the user's session.

Inside Suspense: user-specific content (cart, recommendations), real-time inventory or pricing, A/B cookie reads, any component calling cookies(), headers(), or searchParams.

How do PPR and use cache compose?

'use cache';
import { cacheLife, cacheTag } from 'next/cache';

export async function ProductDescription({ slug }: { slug: string }) {
  cacheLife('minutes');
  cacheTag(`product-desc-${slug}`);
  const desc = await db.product.findUnique({ where: { slug }, select: { description: true } });
  return <p>{desc?.description}</p>;
}

PPR controls the CDN boundary. use cache memoizes origin renders inside Suspense. Both stack: CDN for the shell, component cache for the dynamic parts.

When should I use PPR vs. full dynamic rendering?

Use PPR when the page is mostly static with isolated dynamic sections â€” a product page with real-time inventory, a SaaS dashboard with a cached sidebar plus live metrics. If the entire page depends on per-request data, full dynamic rendering is simpler.

FAQ

Q: Does PPR require changes to Server Components or Suspense?
A: No. Only the config flag and per-route export. All existing patterns work unchanged.

Q: What happens to SEO with PPR?
A: The static shell is fully crawlable HTML from the CDN. Suspense-streamed content may or may not be indexed by crawlers. Keep title, description, and primary body text in the static shell.

Q: Can I use PPR and ISR on the same route?
A: No. A route opts into either PPR or ISR. PPR replaces ISR: static shell is the build-time snapshot, dynamic Suspense children are always fresh.

Q: Is PPR stable in Next.js 15 and 16?
A: Incremental opt-in, experimental through Next.js 16. Production-safe (Vercel uses it internally) but API may change before graduating to stable.

Q: How do I verify PPR is working?
A: Run next build. Routes with PPR show a split between static and dynamic segments in terminal output. In Chrome DevTools Network, the response arrives in chunks: static shell first, then the Suspense stream.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

I Replaced ESLint and Prettier with Biome on Two Production Repos

Ahmed Mahmoud — Sun, 12 Jul 2026 00:12:27 +0000

Headline: Biome is a single Rust-based toolchain that formats and lints JavaScript and TypeScript in one pass, replacing the ESLint + Prettier pair. On two production repos it collapsed two configs, two dependency trees, and two editor plugins into one binary â€” and turned the lint-and-format step from several seconds into well under a second. It does not yet cover every ESLint plugin, so here is where it won and where I kept ESLint.

For years my default JS setup was ESLint for correctness, Prettier for formatting, eslint-config-prettier to keep them from arguing, and an import-sorting plugin. It works, but it is four dependencies, two configs, two editor extensions, and a pre-commit hook running two tools. Biome â€” one Rust binary that does both â€” has matured enough that I migrated two production repos to it. These are the field notes.

Key takeaways

Biome replaces both ESLint and Prettier with one binary, one config (biome.json), and one command, biome check --write, that formats, lints, and organizes imports in a single pass.
The migration is mostly automated: biome migrate eslint --write and biome migrate prettier --write translate your configs, but plugin-specific rules do not carry over.
Biome 2.0 added type-aware lint rules that run without the TypeScript compiler, so noFloatingPromises works without wiring up tsc.
Speed is the headline win: one Rust binary runs format, lint, and import sorting in parallel, finishing a large repo in a fraction of the time ESLint + Prettier takes.
It is not a complete ESLint replacement yet: the plugin ecosystem is young, so you may run Biome and ESLint side by side.

What does Biome actually replace?

Biome is a single toolchain combining a formatter (a near-drop-in Prettier replacement) and a linter (an ESLint-style rule engine) in one Rust binary. It stands in for four parts at once: Prettier, ESLint, the eslint-config-prettier glue, and a separate import-sorting plugin. One biome.json holds formatter options, lint rules, and import organization, and one command does the whole job:

# format, lint, and organize imports in a single pass
biome check --write .

When should I switch from ESLint and Prettier to Biome?

Switch when your linting stack has become its own maintenance burden and you are not relying on niche ESLint plugins. The signals that pushed me: lint + format slow enough to notice in CI or pre-commit; an ESLint config that has drifted into flat-config plus plugins nobody fully understands; mostly standard rules rather than custom ones; and wanting type-aware rules without the full type-check cost.

How do I migrate an existing ESLint + Prettier setup?

npm i -D --save-exact @biomejs/biome
npx biome migrate eslint --write
npx biome migrate prettier --write

biome migrate eslint maps ESLint rules with Biome equivalents into biome.json; biome migrate prettier copies your Prettier options so formatting stays visually identical. Rules from plugins without a Biome counterpart are dropped, so diff the generated config against your old rule list and make a call on each gap. Then delete ESLint, Prettier, and eslint-config-prettier, and re-point the pre-commit hook and editor at Biome.

What does Biome 2.0's type-aware linting change?

Biome 2.0 introduced type-aware lint rules that run without invoking the TypeScript compiler. ESLint rules that reason about types need typescript-eslint with type information, which runs tsc as part of linting â€” usually the slowest part. Biome does its own lightweight type inference in Rust, so noFloatingPromises works without a type-check pass. It will not replace tsc for build-time type safety, but for the type-aware rules it covers it is far cheaper to run.

How does Biome work in a monorepo?

Biome 2.0 supports nested config: a root biome.json defines shared defaults, and each package extends it and overrides locally with "extends": "//":

// packages/api/biome.json
{
  "extends": "//",
  "linter": {
    "rules": {
      "suspicious": { "noConsole": "error" }
    }
  }
}

Biome vs ESLint + Prettier at a glance

Dimension	ESLint + Prettier	Biome
Moving parts	Two tools, two configs, a glue package	One binary, one `biome.json`
Implementation	JavaScript	Rust
Speed on a large repo	Several seconds	Typically sub-second
Import sorting	Separate plugin	Built in
Type-aware rules	Need typescript-eslint + tsc	Built-in inference, no tsc
Plugin ecosystem	Thousands of mature plugins	Young (GritQL plugins)
Formatting	Prettier	Near-Prettier parity

What still keeps me on ESLint?

Biome's rule set does not yet match every rule from plugins like eslint-plugin-jsx-a11y or eslint-plugin-import, and its GritQL plugin story is far younger than ESLint's ecosystem. On one repo with strict accessibility rules and a couple of custom org-specific rules, I kept a slim ESLint config for exactly those and let Biome own formatting, import sorting, and the bulk of correctness linting. Scoping ESLint down to the few rules Biome cannot express still removed most of the old overhead.

FAQ

Q: Is Biome a drop-in replacement for Prettier?
A: For formatting it is near-drop-in â€” Biome targets high Prettier compatibility, and you will see only a handful of edge-case differences after migrating.

Q: Does Biome need the TypeScript compiler for type-aware rules?
A: No. Since Biome 2.0, rules like noFloatingPromises run on Biome's own inference without tsc. Biome does not replace tsc for full type checking.

Q: Can I run Biome and ESLint at the same time?
A: Yes â€” a common transitional setup. Let Biome handle formatting, imports, and standard rules, and keep a scoped ESLint config only for plugin rules Biome has no equivalent for.

Q: Which languages does Biome support?
A: JavaScript, TypeScript, JSX/TSX, JSON, and CSS, with GraphQL support and more progressing. Markdown and YAML formatting are still maturing.

Q: How do I migrate without hand-writing a config?
A: Install @biomejs/biome, then run biome migrate eslint --write and biome migrate prettier --write. Review the generated biome.json, since rules from unsupported plugins are dropped.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

TanStack Query in 2026: What Server Components Didn't Replace

Ahmed Mahmoud — Sun, 12 Jul 2026 00:09:00 +0000

Headline: When React Server Components and Server Actions landed, the loudest take was "you don't need a client data-fetching library anymore." After two years of shipping App Router apps, that's half true. RSC replaced the default fetch, not the whole job â€” here's where I still reach for TanStack Query, and where I've deleted it.

What RSC and Server Actions actually replaced

For a page's initial data, a server component that awaits your database is simpler than anything a client library gives you: no loading state, no client-side waterfall, no serialization boilerplate, and the data never becomes JSON the browser re-parses.

// app/dashboard/page.tsx â€” no client library involved
export default async function Dashboard() {
  const projects = await db.query.projects.findMany();
  return <ProjectList projects={projects} />;
}

For simple mutations, a Server Action plus revalidatePath covers create/update/delete without a mutation hook or a query key. If your app is mostly forms and page-level reads, ship it without a client cache â€” it'll be smaller and easier to reason about. I deleted TanStack Query from two projects that fit this shape and didn't miss it.

Where a client cache still earns its place

Every case where I kept TanStack Query shares one trait: the data changes on the client's timeline, not the request's. Server components render once per request. The moment the UI needs to poll, refetch, paginate, or share cached data across routes without a full navigation, you're back in client-cache territory.

Polling / near-real-time. A build-status widget needs refetchInterval. There's no server-component equivalent to "re-run every few seconds without navigating."
Infinite scroll. useInfiniteQuery manages cursors, dedupes in-flight requests, and keeps prior pages mounted.
Cross-route cache sharing. When several routes read the same current user or org settings, a shared cache serves them instantly on client navigation.
Optimistic updates across components. useOptimistic is great for one form; when a mutation should optimistically touch a list, a counter, and a header badge at once, a shared cache with setQueryData is cleaner.

The pattern that makes them coexist: hydration

The mistake I made early was treating it as either/or. The best setup uses both â€” fetch on the server, hand the result to TanStack Query so the client cache starts warm and the first render has zero loading state.

// app/projects/page.tsx (Server Component)
const qc = new QueryClient();
await qc.prefetchQuery({
  queryKey: ['projects'],
  queryFn: () => db.query.projects.findMany(),
});
return (
  <HydrationBoundary state={dehydrate(qc)}>
    <ProjectsClient />
  </HydrationBoundary>
);

The client reads the same query key, renders instantly from the hydrated cache, and owns freshness from there â€” polling, refetch-on-focus, and invalidation all work as usual.

Mutations: revalidatePath vs invalidateQueries

This is where I see the most confusion. Both invalidate caches â€” different caches. revalidatePath re-renders server components for a route; invalidateQueries refetches a client query. If your data lives in the client cache, a Server Action that only calls revalidatePath won't touch it.

const { mutate } = useMutation({
  mutationFn: (input: NewProject) => createProject(input), // server action
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['projects'] }),
});

My rule: one owner per piece of data. If a value is read through useQuery, the mutation that changes it must invalidate that query â€” don't rely on revalidatePath to keep the client cache honest.

My current decision rule

Start without it. Render reads in server components, write through Server Actions, and add TanStack Query only when a concrete need shows up: polling, infinite scroll, a shared client cache across routes, or multi-component optimistic updates. Adding it later is a small, local change; ripping out a cache you didn't need is not. RSC and a client cache answer different questions â€” one owns the initial server render, the other owns client-timeline freshness â€” and the apps I'm happiest with use each for exactly what it's good at.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

useOptimistic in React 19: Patterns and Pitfalls from Real Forms

Ahmed Mahmoud — Sun, 12 Jul 2026 00:05:37 +0000

Headline: React 19's useOptimistic shows the result of an action before the server confirms it. The API is tiny; the mental model is where people trip. Here's what held up across a comment box, a like button, and a settings form â€” plus three edges that cost me an afternoon each.

The mental model

useOptimistic stores nothing durable. It's a view over your real state that is only live while a transition is pending.

const [optimistic, addOptimistic] = useOptimistic(
  realState,
  (current, action) => nextState
);

The first arg is the source of truth; the second is a pure reducer. The instant your action resolves and realState updates, React throws the optimistic value away and re-renders from truth. You never manually roll back.

Pattern 1: append on submit

const [optimisticComments, addOptimistic] = useOptimistic(
  comments,
  (state, text: string) => [...state, { id: crypto.randomUUID(), text, pending: true }]
);

The pending flag drives a dimmed style; the server action revalidates the list so it refreshes from source.

Pitfall 1: fire it inside a transition

Calling addOptimistic from a plain onClick makes the value flash and vanish â€” there's no pending transition to keep it alive. Always trigger it from a form action or startTransition.

Pattern 2: toggle with a count

const [state, toggle] = useOptimistic(
  { liked, count },
  (s) => ({ liked: !s.liked, count: s.count + (s.liked ? -1 : 1) })
);

Because the reducer receives the current optimistic value, rapid double-clicks compose correctly instead of fighting a stale closure.

Pitfall 2: errors need their own signal

useOptimistic has no error channel. When the action throws, the optimistic value disappears â€” correct â€” but the user gets no explanation. Pair it with useActionState or a toast.

Pitfall 3: unique temporary keys

Reusing id: 'temp' for every pending row makes React merge concurrent entries. Give each optimistic item a unique temp key and let the server row replace it on revalidation.

When I skip it

For low-confidence writes â€” payments, destructive deletes, heavy validation â€” I keep an honest pending state. Showing success you can't guarantee erodes trust faster than a spinner.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

DEV Community: Ahmed Mahmoud

Route Handlers vs Server Actions in Next.js: When I Reach for Each

Key takeaways

What is a Server Action vs a Route Handler in Next.js?

When should I use a Server Action instead of a Route Handler?

When should I use a Route Handler instead of a Server Action?

How do Route Handlers and Server Actions compare?

Do I need a Route Handler to fetch data for my own page?

Are Server Actions and Route Handlers both public endpoints?

FAQ

URL State in the Next.js App Router: How I Stopped Losing UI State on Refresh

Key takeaways

When should I store state in the URL instead of useState?

How do I read search params in the Next.js App Router?

How do I write to the URL without triggering a full navigation?

What is nuqs, and what does useQueryState add?

Native searchParams or nuqs — which should I pick?

What breaks — Suspense, throttling, and stale server data?

FAQ

Error Handling in the Next.js App Router: How I Stopped One Throw From Blanking the Page

Key takeaways

What does error.tsx actually catch in the App Router?

Why must error.tsx be a Client Component?

When do I need global-error.tsx instead of error.tsx?

How do I handle "not found" separately from errors?

Why are my server error messages replaced with a digest in production?

How do I recover without a reload — and what about event-handler errors?

The App Router error files at a glance

FAQ

View Transitions in Next.js: How I Added Animated Page Changes Without a Library

Key takeaways

What is the View Transitions API, and what problem does it solve?

How do I run my first view transition?

How do I animate one element independently?

How do I add view transitions to Next.js App Router navigation?

What is React's <ViewTransition> component, and is it ready?

What breaks — duplicate names, reduced motion, and performance?

FAQ

Debugging Hydration Mismatches in the Next.js App Router

Key takeaways

What is a hydration mismatch, and why does it break the page?

Why do Date.now() and localStorage cause a hydration error?

When should I use suppressHydrationWarning?

How do I render a client-only value without a mismatch?

Why do browser extensions cause hydration errors on <body>?

How do I fix invalid HTML nesting mismatches?

FAQ

Fixing INP: Field Notes on Interaction to Next Paint in a React App

Key takeaways

What is INP and how is it different from FID?

What are the three phases of an interaction?

How do I fix input delay?

How do I fix processing time?

How do I fix presentation delay?

How do I measure INP in the field?

FAQ

Next.js Server Actions Are Public Endpoints: How I Lock Them Down

Why Server Actions Are Different

The Mistakes I See Most

1. Assuming "use server" Means Private

2. Missing Session Checks Inside Actions

3. Trusting Client-Provided Values Without Validation

The Pattern I Now Use Everywhere

Rate Limiting and Abuse Prevention

What I Recommend Auditing Now

React Compiler in 2026: What It Actually Memoizes (And What It Doesn't)

Key takeaways

What does React Compiler actually do?

How do I enable it in Next.js?

What does the compiler memoize?

When does it opt out?

The "use no memo" escape hatch

Should I delete useMemo and useCallback?

Manual vs compiler memoization

FAQ

Partial Prerendering in Next.js: The Static Shell + Dynamic Stream Model

Key takeaways

What does PPR actually do?

How is PPR different from ISR and streaming Suspense?

How do I enable PPR?

What is React's `<ViewTransition>` component, and is it ready?

Why do `Date.now()` and `localStorage` cause a hydration error?

When should I use `suppressHydrationWarning`?

Why do browser extensions cause hydration errors on `<body>`?

1. Assuming `"use server"` Means Private

The `"use no memo"` escape hatch