DEV Community: Parsa Jiravand

Your Recipe App Is Hiding a Silent Video

Parsa Jiravand — Sun, 06 Sep 2026 10:37:22 +0000

Open dev tools on almost any recipe site mid-scroll and check the Elements panel. Buried near the bottom, there's a <video> tag. It's one pixel. It's muted. It's on an infinite loop. And if you actually watch what it's playing — nothing. It's a single frame of black, looping forever, going nowhere.

That's not debug cruft someone forgot to delete. It's load-bearing. Rip it out and the page's actual job — keeping your phone's screen on while your hands are covered in flour — quietly breaks.

The problem it's solving

Mobile browsers don't give a web page a button that says "don't lock the screen." There's no document.staySharp(). The OS owns that timer, and for a long time the only way JavaScript could influence it was indirectly — by doing something the OS already treats as a signal that the user is still engaged.

Actively playing video is one of those signals. Every mobile OS defers the screen-lock timer while media is playing, because pausing a movie mid-scene to lock the screen would be a terrible experience. So people found the seam: play something, even if that something is deliberately nothing.

<video id="keep-awake" muted playsinline loop>
  <source src="silent-1px.mp4" type="video/mp4" />
</video>
<script>
  document.getElementById("keep-awake").play();
</script>

muted and playsinline are load-bearing too — without them, most mobile browsers either block the autoplay outright or hijack the screen with a fullscreen player. Libraries like NoSleep.js packaged exactly this pattern for years, because it worked, and because there wasn't anything better to reach for.

Where it falls apart

It's a real technique and it did the job — but borrowing "video playback" as a proxy for "keep the screen awake" comes with everything you'd expect from repurposing the wrong primitive:

Autoplay policies fight you. Some mobile browsers still block autoplaying video unless it happens inside a user gesture, so the trick can silently fail on exactly the browser version where you need it most.
It costs a decoder, not a flag. A one-pixel video is small, but "small" isn't "free" — you're spinning up video decoding hardware and a render loop to communicate a boolean.
Nothing tells you it stopped working. If the tab is backgrounded in a way the browser doesn't treat as "still playing," the video pauses and your screen locks — with no error, no event, nothing to catch.
It's semantically a lie. Anyone reading that markup six months from now has to reverse-engineer why there's a phantom video before they can safely touch it.

The workaround earned its keep because the platform had a real gap. In 2019, Chrome closed it.

The API that says what it means

🎮 Try it yourself

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

The Screen Wake Lock API does exactly one thing, and its name doesn't lie about it:

let wakeLock = null;

async function requestWakeLock() {
  try {
    wakeLock = await navigator.wakeLock.request("screen");
    console.log("Screen will stay on");
  } catch (err) {
    // Fails if the document isn't visible, isn't a secure context,
    // or the platform refuses for its own reasons.
    console.error(`${err.name}: ${err.message}`);
  }
}

navigator.wakeLock.request("screen") — "screen" is currently the only lock type the spec defines — returns a promise for a WakeLockSentinel. While that sentinel is alive, the screen won't dim or lock on its own. No <video>, no decoder, no lying markup. It needs a secure context (HTTPS or localhost) and the document has to actually be visible when you call it, or the promise rejects with a NotAllowedError.

Releasing it is just as direct:

async function releaseWakeLock() {
  await wakeLock?.release();
  wakeLock = null;
}

That would be the whole post, except the API has one behavior that catches almost everyone the first time.

The part the happy path hides

Switch away from the tab holding the lock — another window, another app, the phone's lock button — and the browser releases the wake lock for you. Silently. No exception. No rejected promise. Your wakeLock variable still points at a sentinel object; it's just that the sentinel's job is now over, and nothing forces you to notice.

Come back to the tab, and the screen goes right back to locking on schedule — because as far as the platform's concerned, you never asked it not to. If your only test was "click the button once, watch the screen stay on for thirty seconds," you'll ship this and find out from a support ticket instead.

The sentinel does expose a release event, and MDN's own guide handles the whole thing with a visibilitychange listener that re-requests the lock the moment the tab becomes visible again:

document.addEventListener("visibilitychange", async () => {
  if (wakeLock !== null && document.visibilityState === "visible") {
    await requestWakeLock();
  }
});

One wrinkle worth planning for yourself: that condition only checks "did we ever request a lock," not "does the user still want one." If you also let people manually turn the feature off, null out wakeLock on that path too — otherwise switching tabs and back will quietly turn a lock the user explicitly released back on.

Ship it without breaking the browsers that don't have it

Feature-detect before you touch any of this:

if ("wakeLock" in navigator) {
  requestWakeLock();
} else {
  // Fall back to whatever you were doing before, or do nothing —
  // a screen that locks isn't a crash.
}

Support is solid across Chrome, Edge, and Opera, and Safari added it in 16.4. Firefox has historically lagged on this one — check caniuse.com for the current state before you rely on it, and always keep the feature-detect branch rather than assuming.

The one-pixel video, decoded

Next time a cooking site keeps your screen alive while you're up to your elbows in dough, you'll know what's happening under the hood — and whether it's a phantom <video> tag or three lines calling an API built for exactly that job.

If you're still shipping the video trick somewhere, what's holding you back from swapping it — browser support, or just not knowing the replacement existed?

🧠 Test yourself

Think it clicked? Take the 7-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected:

⭐ GitHub — follow me and star the projects: github.com/parsajiravand
💬 Discord — join the frontend best-practices community: discord.gg/d9KRhuAwQ
📸 Instagram — frontend best practices, daily: @bestpractice___

React Compiler 1.0: What useMemo You Can Delete

Parsa Jiravand — Sat, 05 Sep 2026 10:17:49 +0000

Open any React codebase built before late 2025 and you'll find the same defensive scaffolding in nearly every component: a memo() wrapper here, a useCallback there, a useMemo around a sort you were never quite sure was expensive enough to justify it. Most of that code was never a response to a measured problem — it was insurance against a re-render you were guessing might happen.

As of React Compiler 1.0, stable since October 2025, that guessing game is mostly over. The compiler does the same analysis you were doing by hand, applies it more precisely than hooks alone can, and in a few cases does things manual memoization structurally cannot do at all. This is episode two of React Deep Dive, and it's about what "automatic memoization" actually means, what it removes from your code, and what it deliberately leaves for you to keep deciding.

This article is written against React 19.2 (verified 19.2.8, the current npm release as of this writing) and React Compiler 1.0 (the stable babel-plugin-react-compiler@1.0.0 release, shipped October 7, 2025 at React Conf — verified against React's own release notes). If you want the re-render vocabulary this article leans on, episode one covered re-render vs. remount — useful background, not required reading.

What you'll learn

By the end of this article you'll be able to:

Explain why React re-renders a whole subtree by default, and what memoization actually buys you when you add it
Read code with React.memo, useMemo, and useCallback and know exactly what problem each one was solving
Describe what React Compiler automates, including two cases manual hooks can't solve at all
Know when you still need useMemo/useCallback even with the compiler installed
Add the compiler to a project and read its lint diagnostics when it can't safely optimize something

Who this is for

You've written function components and used useState, useEffect, and at least one of useMemo/useCallback/React.memo before, even if you couldn't fully explain why. No compiler internals or build-tooling experience required.

The problem: manual memoization doesn't scale
The mental model: what memoization actually buys you
Stage 1: the re-render, without memoization
Stage 2: the manual fix, and its subtle crack
Stage 3: the same code, compiled
Stage 4: turning it on
Edge cases and gotchas
Best practices
FAQ
Cheat sheet
Key takeaways

The problem: manual memoization doesn't scale

Here's a dashboard with a search box and a team roster underneath it. Nothing exotic:

function Dashboard({ members }) {
  const [query, setQuery] = useState("");

  return (
    <div>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      <TeamRoster members={members} onInvite={(id) => sendInvite(id)} />
    </div>
  );
}

function TeamRoster({ members, onInvite }) {
  const sorted = sortByActivity(members); // recomputed on every call
  return (
    <ul>
      {sorted.map((m) => (
        <MemberCard key={m.id} member={m} onInvite={() => onInvite(m.id)} />
      ))}
    </ul>
  );
}

members never changes while you type. But every keystroke updates query, which re-renders Dashboard, which re-renders TeamRoster — by default, with no memoization applied anywhere, React re-renders a component and everything below it whenever the component's own state or a parent's state changes. TeamRoster re-runs sortByActivity from scratch, builds a brand-new array, and hands every MemberCard a brand-new onInvite closure. Every card re-renders, on every keystroke, for a value that didn't change.

The textbook fix is to memoize the boundary:

const TeamRoster = memo(function TeamRoster({ members, onInvite }) {
  const sorted = useMemo(() => sortByActivity(members), [members]);
  const handleInvite = useCallback((id) => onInvite(id), [onInvite]);

  return (
    <ul>
      {sorted.map((m) => (
        <MemberCard key={m.id} member={m} onInvite={() => handleInvite(m.id)} />
      ))}
    </ul>
  );
});

This helps — sortByActivity only re-runs when members actually changes. But look closely at the line that renders each card: onInvite={() => handleInvite(m.id)}. That inline arrow function is created fresh on every render, useCallback wrapper or not, so MemberCard still gets a new onInvite prop every time and still re-renders. useCallback cannot fix this without restructuring the code — hooks can only stabilize values, and the value here is the arrow function around handleInvite, not handleInvite itself.

This is the actual shape of the problem: correct manual memoization requires you to trace every value that flows into every child, on every edit, forever. Miss one spot — and the spot above is easy to miss — and the memoization you added silently does nothing.

The mental model: what memoization actually buys you

The mental model: React re-renders a component whenever its own state changes and whenever its parent re-renders — regardless of whether the props it receives actually changed. Memoization doesn't stop a component from re-rendering because of its own state; it gives React a way to tell that a child's inputs didn't change, so React's reconciler can skip that child's subtree entirely rather than re-run it and diff the result.

Concretely: if a component returns the exact same element reference on two consecutive renders (not just equal-looking JSX, the same object in memory), React bails out of that subtree without touching it. React.memo gets you this by comparing props before re-rendering the child; useMemo/useCallback get you this by keeping the values passed into JSX stable, so the JSX built from them stays stable too.

React Compiler's entire job is producing that same stability automatically, everywhere it's provably safe to do so — by reading your component's code and figuring out, per value, whether it could have changed since the last render. It doesn't change when your component's own state causes it to re-render. It changes whether that re-render cascades into components that had nothing to do with the change.

Stage 1: the re-render, without memoization

Run the Dashboard/TeamRoster code above and every MemberCard logs a render on every keystroke — you can watch this happen for real in the playground below, which runs the actual React 19.2.8 runtime, not a simulation. This is React doing exactly what it's documented to do: no memoization means no bailout, so the whole subtree re-runs.

Key concept: an unmemoized re-render isn't a bug. It's React's default, and it's usually fine — React is fast enough that most re-renders never cost anything a user would notice. The problem only shows up when a subtree is expensive enough, or large enough, that redoing it on every keystroke becomes visible.

🎮 Try it yourself

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

Stage 2: the manual fix, and its subtle crack

The memo/useMemo/useCallback version above fixes the expensive sort but not the inline arrow, for a structural reason worth sitting with: hooks can only be called unconditionally, at the top level of a component, so you can't useCallback a function that's constructed inside a .map() callback per item — you'd be calling a hook in a loop, which breaks the Rules of Hooks. The only fix within hooks alone is to restructure the code, usually by pushing the click handler down into MemberCard and passing just the id.

Key concept: manual memoization isn't just tedious, it has real structural gaps — situations no combination of useMemo/useCallback/React.memo can close without changing how the code is written. That's the opening React Compiler was built to close.

Stage 3: the same code, compiled

With React Compiler enabled, you write the first version of TeamRoster — no memo, no useMemo, no useCallback, the inline arrow left exactly where it reads most naturally:

function TeamRoster({ members, onInvite }) {
  const sorted = sortByActivity(members);
  return (
    <ul>
      {sorted.map((m) => (
        <MemberCard key={m.id} member={m} onInvite={() => onInvite(m.id)} />
      ))}
    </ul>
  );
}

The compiler analyzes the function body at build time and rewrites it — roughly, generating memoized slots for sorted and for each card's element, comparing them against the previous render's values, and reusing the old result when nothing relevant changed. According to React's own compiler documentation, this handles the inline-arrow case correctly with or without the arrow function, because the compiler is reasoning about the whole function's data flow, not applying a hook to a single named value.

This part is a model, not a live demo: React Compiler is a build-time Babel transform, so it cannot run inside a static HTML page without a bundler. The playground above shows the real, measurable effect — fewer re-renders — that flipping "apply manual memoization" produces with the actual React runtime; the compiled output is the same effect, generated for you, from the plain code shown here.

Two things the compiler can do that manual hooks structurally can't, both documented in its own release notes:

Memoize after an early return. useMemo and useCallback can't appear after a conditional return — that's the Rules of Hooks. The compiler isn't a hook, so it can memoize values computed after one.
Handle the inline-arrow case above without you restructuring anything.

Stage 4: turning it on

Installing it is a dev dependency plus a build-tool integration:

npm install --save-dev --save-exact babel-plugin-react-compiler@latest
npm install --save-dev eslint-plugin-react-hooks@latest

eslint-plugin-react-hooks's recommended and recommended-latest presets now ship the compiler's lint rules directly — this replaced the separate eslint-plugin-react-compiler package when the compiler went stable, and the lint rules work even in projects that haven't added the compiler itself yet, because they're really flagging Rules-of-React violations.

New projects scaffolded with recent versions of Vite, Next.js (15.3.1+), or Expo (SDK 54+) can start with the compiler already wired in. Existing codebases adopt it incrementally: point the compiler at one directory or route first, watch the lint output, and expand from there.

Edge cases and gotchas

It only compiles components and hooks — not arbitrary functions. A plain helper function called from inside a component gets memoized as a call, but if that same expensive helper is called from three different components, each one still pays the cost independently; the compiler's memoization isn't shared across components.
It requires the Rules of React. The compiler assumes your components and hooks are pure — idempotent given the same props/state, no mutating props or state during render, no side effects in render. Code that breaks these rules in ways the compiler can statically detect gets flagged (surfaced through eslint-plugin-react-hooks, with rules like set-state-in-render and set-state-in-effect); code that breaks them in ways JavaScript can't statically catch may compile without warning and behave subtly differently than before.
Removing existing manual memoization isn't automatically safe. React's own guidance is to leave existing useMemo/useCallback calls in place, or test carefully before deleting them — the compiler's memoization boundaries won't always land in exactly the same places yours did, and if some effect elsewhere depends on one of your values staying referentially stable across specific renders, changing that boundary can change how often that effect fires.
React 17 and 18 are supported, not just 19 — with a target config option and the react-compiler-runtime package as an added dependency. On React 19 neither is needed.
It's a build-time transform, full stop. There's no runtime flag or devtools toggle; if it isn't wired into your bundler's config, none of this applies to your app.

Best practices

New code: stop hand-memoizing by default. Write the plain version. Reach for useMemo/useCallback only when you need explicit control over a value's identity — most commonly, when that value is a dependency of an effect and you need to guarantee it won't cause the effect to over-fire.
Turn on the compiler-powered lint rules even before you install the compiler. They're Rules-of-React checks, and they catch real bugs (state updates during render, unsafe ref reads) independent of whether you've adopted the compiler yet.
Adopt incrementally in an existing codebase. Compile one route or directory, watch for lint diagnostics and behavior regressions, then widen the scope. Pin the compiler to an exact version (--save-exact) rather than a semver range if your test coverage is thin, since future versions may change memoization boundaries.
Don't reach for the compiler to fix a slow function. If sortByActivity above were genuinely expensive, calling it from several components would still re-run it in each one — profile first, and consider your own caching if the same expensive call is duplicated across the tree.
Use "use no memo" as a scalpel, not a habit. It opts one function out of compilation, useful while debugging a compiler diagnostic or isolating code the compiler can't yet handle — not a default you sprinkle everywhere "to be safe."

FAQ

Does React Compiler replace useEffect?

No. The compiler is entirely about memoizing render-time values and JSX; effects are how you synchronize with something outside React, and the compiler has no opinion on what belongs in one or when it should run.

Do I still need React.memo, useMemo, or useCallback with the compiler installed?

Not by default — the compiler applies equivalent memoization automatically in most cases. They remain available as an explicit escape hatch, most notably when a value is used as an effect's dependency and you need to guarantee its identity stays stable on purpose.

Is it safe to delete all my existing useMemo/useCallback calls right now?

Not automatically. React's own release guidance is to leave existing memoization in place, or remove it only after careful testing, because the compiler's generated memoization can land on slightly different boundaries than yours did.

Does React Compiler work with React 18 or older?

Yes — it supports React 17 and up. Below React 19 you add a target in the compiler config and depend on react-compiler-runtime; on React 19 that extra dependency isn't needed.

What happens if my component breaks the Rules of React?

The compiler's validation passes encode the Rules of React and surface violations as diagnostics through eslint-plugin-react-hooks. Statically detectable violations get flagged rather than silently miscompiled; violations JavaScript can't detect at compile time are the reason React recommends good test coverage before relying on the compiler in production.

How do I stop the compiler from touching one specific component?

Add the "use no memo" directive as the first line of that function's body.

Cheat sheet

Task	Before (manual)	With React Compiler	Notes
Skip re-rendering a child when unrelated state changes	`React.memo(Child)`	Automatic	Compiler keeps the child's JSX reference stable so React's reconciler bails out
Stabilize a callback passed to a memoized child	`useCallback(fn, [deps])`	Automatic	Handles inline arrows written straight in JSX, which manual hooks can't
Avoid recomputing an expensive render-time value	`useMemo(() => calc(x), [x])`	Automatic	Only for values computed inside a component or hook
Memoize a value defined after an early return	Not possible — breaks Rules of Hooks	Automatic	One of the compiler's documented advantages over hooks
Guarantee a value's identity for an effect dependency	`useMemo`/`useCallback`	Still `useMemo`/`useCallback`	Documented escape hatch — keep using it here
Opt one function out of compilation	—	`"use no memo"` directive	For debugging or code incompatible with the compiler
Enable Rules-of-React lint checks	`eslint-plugin-react-compiler` (superseded)	`eslint-plugin-react-hooks@latest`, `recommended` preset	Ships the compiler's lint rules directly since 1.0
Run on React 17/18	—	Add `react-compiler-runtime` + `target` config	React 19 needs neither

# Minimal install for a React 19 project
npm install --save-dev --save-exact babel-plugin-react-compiler@latest
npm install --save-dev eslint-plugin-react-hooks@latest

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

Key takeaways

React re-renders a component's whole subtree by default whenever its state changes; memoization's actual job is giving children a stable reference so React's reconciler can bail out of re-rendering them.
React Compiler 1.0, stable since October 2025, automates that memoization at build time — including cases hooks structurally cannot solve, like an inline arrow written in JSX or a value defined after an early return.
It only compiles components and hooks that hold to the Rules of React, and it only memoizes work inside them — not arbitrary functions shared across components.
useMemo/useCallback aren't obsolete. Keep them where a value's referential identity is a correctness requirement, like an effect dependency, and don't strip existing memoization from old code without testing first.

The pile of useMemo/useCallback/memo() wrappers from the opening paragraph isn't gone because you finally found time to delete it by hand — it's gone because, as of React 19.2 with the compiler enabled, you stop needing to write most of it in the first place. The insurance policy against re-renders you were never sure would happen is now something the build step carries for you.

Have you turned the compiler on in a real codebase yet — did the lint rules catch anything you didn't expect? Tell me in the comments.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected:

⭐ GitHub — follow me and star the projects: github.com/parsajiravand
💬 Discord — join the frontend best-practices community: discord.gg/d9KRhuAwQ
📸 Instagram — frontend best practices, daily: @bestpractice___

Your Timer Doesn't Know You Tabbed Away

Parsa Jiravand — Sat, 05 Sep 2026 10:17:18 +0000

Picture a dashboard tile polling an endpoint every two seconds to keep a number fresh. You switch to Slack to answer a message. Four minutes later you're still there, and the tile is still polling — a request every two seconds, into a tab nobody has looked at since you left it.

Multiply that by however many tabs your users leave open, and it's not a rounding error. It's server load and battery drain for work that produces zero value, because the one piece of information that would have stopped it — is anyone actually looking at this — was never checked.

The fix that feels obvious

The instinct is to pause on blur and resume on focus. It reads clean:

window.addEventListener("blur", () => clearInterval(pollId));
window.addEventListener("focus", () => { pollId = startPolling(); });

Ship that, and eventually someone files a strange bug: a video that's supposed to keep playing in the background pauses when they click into DevTools. Or a live ticker that stops updating the instant they open a browser extension's popup. Or — the one that's easy to miss because it only happens on multi-monitor setups — a dashboard that "goes idle" while it's sitting fully visible on a second screen, because the user is typing in a different app on their main monitor.

None of those tabs are hidden. The content is right there on the glass. blur fired anyway, because blur and focus answer a narrower question than the one you actually asked.

The question you meant to ask

blur/focus tell you whether a window has keyboard focus. That's genuinely useful for things like "should this input show its focus ring" — it is not the same as "can a human currently see this content." A window can lose focus while staying fully rendered and visible; that's exactly the second-monitor case above, and it's why MDN's own guidance singles this out when explaining why the Page Visibility API exists at all, rather than just reusing focus events.

The API that answers the real question is small:

document.visibilityState — "visible" or "hidden".
document.hidden — the older boolean shorthand for the same thing.
the visibilitychange event, fired on document whenever that state flips.

It goes "hidden" when the tab is switched away from, the window is minimized, or (on most platforms) the screen locks — the set of conditions where the content is, as far as the browser can tell, definitely not on anyone's retina. It stays "visible" in the second-monitor case above, because it correctly is. This has been standard and unprefixed in every evergreen browser for well over a decade — there's no feature-detection dance required.

🎮 Try it yourself

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

Wiring it up properly

Swap the listener, not just the vocabulary:

let pollId = null;

function startPolling() {
  pollId = setInterval(fetchLatest, 2000);
}

function stopPolling() {
  clearInterval(pollId);
  pollId = null;
}

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    stopPolling();
  } else if (!pollId) {
    startPolling();
  }
});

if (!document.hidden) startPolling();

That's the whole change. But there's a second gotcha waiting even after you've picked the right event: don't trust the tick count to tell you how long the tab was gone.

Browsers throttle timers running in tabs nobody can see — it's a deliberate battery-saving move, and it means a setInterval you started before the tab was hidden won't necessarily fire on schedule while it's backgrounded. If your "time away" logic counts ticks (ticksElapsed * intervalMs), a long background stretch will under-report itself, because some of those ticks simply never fired.

The fix is to stop counting ticks and start reading the clock. Stamp Date.now() on the way out and the way back in:

let hiddenAt = null;

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    hiddenAt = Date.now();
  } else if (hiddenAt) {
    const hiddenMs = Date.now() - hiddenAt;
    reconcile(hiddenMs); // catch up state using real elapsed time
    hiddenAt = null;
  }
});

visibilitychange gives you the exact moments; wall-clock math gives you the exact duration between them. Neither depends on how many timer callbacks the browser decided to actually run in between.

🧠 Test yourself

Think it clicked? Take the 7-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

Focus and visibility are different questions — use the one you mean

The rule of thumb: focus/blur for "does this element or window currently have keyboard input" — form fields, keyboard shortcuts, anything about input. visibilitychange for "can a human currently see this" — video and animation playback, polling and refresh intervals, analytics dwell time, autosave cadence. It's also the more reliable place to flush a last-gasp analytics beacon than beforeunload, since hidden fires on tab close too, and far more consistently across mobile browsers.

Confusing the two isn't a syntax error. It's a background video that stops for the wrong reason, and a poll that never stops for the right one.

What's ticking away in one of your background tabs right now that has no idea nobody's watching?

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected:

⭐ GitHub — follow me and star the projects: github.com/parsajiravand
💬 Discord — join the frontend best-practices community: discord.gg/d9KRhuAwQ
📸 Instagram — frontend best practices, daily: @bestpractice___

NestJS Dependency Injection Explained (with Cheat Sheet)

Parsa Jiravand — Fri, 04 Sep 2026 10:58:05 +0000

Two feature modules, OrdersModule and BillingModule, both list CacheService in their providers array. Both inject it in a constructor. Both call cache.increment('hits'). In staging, the counter never goes above the value each module produced on its own — OrdersModule reports 40 hits, BillingModule reports 12, and the total the dashboard shows is wrong by definition, because there's no single counter to be wrong about.

CacheService is decorated with @Injectable(). Nobody set a scope. By every definition you've read, it's a singleton. It is — just not the singleton you assumed.

What you'll learn

By the end of this article you'll be able to:

Explain what NestJS's dependency injection (DI) container actually does when it sees constructor(private readonly cache: CacheService)
State precisely what "singleton" means in Nest — and why the same @Injectable() class can end up as two separate instances
Choose between useValue, useClass, useFactory, and useExisting when a provider needs more than a bare class
Pick the right provider scope (DEFAULT, REQUEST, TRANSIENT) and predict the performance and correctness consequences of each
Recognize when a provider's scope "bubbles up" and forces something else in your app to become request-scoped too

Who this is for

You've written at least one NestJS service with @Injectable() and injected it into a controller's constructor. You don't need to have written a custom provider, a factory, or a scoped provider yet — we'll build all three from nothing.

This article is written against NestJS 12.x (verified against the nestjs/nest GitHub release history — v12.0.0 shipped August 27, 2026). Provider registration and scopes are core-container behavior, unchanged in shape across the 10.x → 12.x line; nothing here depends on the v12 ESM migration specifically.

The problem: a singleton that isn't
The mental model: registrations, not classes
Stage 1: the simplest provider
Stage 2: sharing one instance across modules
Stage 3: custom providers — when a class isn't enough
Stage 4: provider scopes — DEFAULT, REQUEST, TRANSIENT
Stage 5: scope bubbling
Edge cases and gotchas
Best practices
FAQ
Cheat sheet

The problem: a singleton that isn't

Here's the setup, trimmed to the part that matters:

// cache.service.ts
@Injectable()
export class CacheService {
  private hits = 0;
  increment(key: string) {
    this.hits++;
    return this.hits;
  }
}

// orders.module.ts
@Module({
  controllers: [OrdersController],
  providers: [OrdersService, CacheService],
})
export class OrdersModule {}

// billing.module.ts
@Module({
  controllers: [BillingController],
  providers: [BillingService, CacheService],
})
export class BillingModule {}

Both OrdersService and BillingService inject CacheService through their constructors. Both trust that "singleton" means what it usually means in a dependency-injection framework: one instance, shared by whoever asks for it. That trust is reasonable — and wrong here, because of one detail that's easy to skim past: CacheService appears in the providers array of two different modules.

Nest doesn't ask "has this class been instantiated anywhere in the app?" It asks "has this token been registered in this module's injector?" OrdersModule and BillingModule never import each other or a shared module that exports CacheService, so Nest treats the two listings as two independent registrations — and builds two independent instances. Each service gets a real, working, entirely singleton CacheService. They're just not the same one.

The mental model: registrations, not classes

The mental model: NestJS's DI container isn't one global map from class to instance. It's a tree of injectors, one per module, and each injector only knows about the providers that module registered — either directly in its own providers array, or indirectly, imported from another module that exports them.

A provider's real identity is its token (by default, the class itself) plus where it was registered. "Singleton" is a promise about a registration, not about a class name: within one injector's scope, this token resolves to one instance, created once. If a class gets registered twice — once per module, with no import/export connecting the two — you get two injectors, two registrations, two honestly-singleton instances that have never met.

This is why exports matters so much in Nest, and it's the missing piece in the bug above: to actually share one CacheService, exactly one module should own it and export it, and every consumer should import that module instead of re-listing the class.

// cache.module.ts
@Module({
  providers: [CacheService],
  exports: [CacheService],
})
export class CacheModule {}

// orders.module.ts
@Module({
  imports: [CacheModule],
  controllers: [OrdersController],
  providers: [OrdersService], // CacheService is NOT listed here
})
export class OrdersModule {}

// billing.module.ts
@Module({
  imports: [CacheModule],
  controllers: [BillingController],
  providers: [BillingService], // CacheService is NOT listed here either
})
export class BillingModule {}

Now there's exactly one registration of CacheService, owned by CacheModule. OrdersModule and BillingModule both import it, so Nest resolves the same token to the same instance in both — one counter, correctly shared.

Key concept: if you want one instance across your app, register the provider in exactly one place and import it everywhere else. Never re-list the class in a second module's providers array "to be safe" — that's the line that creates the second instance.

🎮 Try it yourself

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

Stage 1: the simplest provider

The smallest possible provider is just a decorated class:

@Injectable()
export class GreetingService {
  greet(name: string) {
    return `Hello, ${name}`;
  }
}

@Injectable() marks the class as something Nest's container is allowed to manage. Listing it in a module's providers array registers it — Nest instantiates it once, resolving its own constructor dependencies first (constructor injection is recursive: if GreetingService needed a LoggerService, Nest would build that first). Anything that injects GreetingService via its constructor type gets the same instance, because the class itself doubles as its injection token.

Stage 2: sharing one instance across modules

Covered above — the fix is exports plus imports, not a second providers listing. It's worth restating as a rule, because it's the single most common DI mistake in a growing Nest app: a provider is shared by being exported and imported, never by being declared twice.

Stage 3: custom providers — when a class isn't enough

Not every dependency is "a class Nest can new up." Configuration objects, third-party SDK clients, and values that depend on other providers all need something more flexible than the shorthand providers: [CacheService]. Nest's provider registration accepts a full object instead, keyed by provide (the token) and one of four resolution strategies:

@Module({
  providers: [
    // useValue — hand Nest an already-built value
    { provide: 'API_BASE_URL', useValue: 'https://api.example.com' },

    // useClass — pick the implementation at registration time
    { provide: PaymentsGateway, useClass: StripeGateway },

    // useFactory — build the value at runtime, with its own dependencies
    {
      provide: 'DB_CONNECTION',
      useFactory: (config: ConfigService) => createConnection(config.get('DB_URL')),
      inject: [ConfigService],
    },

    // useExisting — an alias: a second token pointing at the same instance
    { provide: 'LEGACY_CACHE', useExisting: CacheService },
  ],
})
export class AppModule {}

'API_BASE_URL' and 'DB_CONNECTION' are string tokens — the class-as-token trick only works when the dependency is a class, so a plain value or an interface needs an explicit token instead. Injecting one of these requires @Inject(), since there's no type for Nest to read off the constructor parameter:

@Injectable()
export class PaymentsService {
  constructor(@Inject('API_BASE_URL') private readonly baseUrl: string) {}
}

Key concept: useValue, useClass, useFactory, and useExisting are four ways to answer the same question — "what does this token resolve to?" — not four unrelated features. useFactory's inject array is exactly the same resolution the container already does for constructors; it's just spelled out explicitly because a factory function has no constructor for Nest to inspect.

Stage 4: provider scopes — DEFAULT, REQUEST, TRANSIENT

Everything so far assumes the default: one instance, created once at bootstrap, reused for the life of the process. That's Scope.DEFAULT, and you never write it — it's what @Injectable() means with no options. Two other scopes exist, each trading that simplicity for something a shared singleton can't do:

@Injectable({ scope: Scope.REQUEST })
export class RequestContextService {
  // A new instance is created for every incoming request,
  // and garbage-collected once that request finishes.
}

@Injectable({ scope: Scope.TRANSIENT })
export class LoggerService {
  // A new instance is created for every consumer that injects it —
  // not shared, not tied to a request.
}

REQUEST scope is for state that's genuinely per-request — the authenticated user, a request ID for tracing, tenant context in a multi-tenant app. TRANSIENT is for the rarer case where you don't want sharing at all, even within one request — a logger that should carry the name of whichever class asked for it is the textbook example.

Both cost something a singleton doesn't. NestJS's own documentation is explicit that request-scoped providers affect performance, because the container can no longer build the dependency graph once at bootstrap — it has to rebuild the request-scoped branch on every request. A properly designed app shouldn't lose more than roughly 5% latency to it, but "properly designed" is doing real work in that sentence: reach for REQUEST scope only for state that actually varies per request, not as a default habit.

For multi-tenant apps where many requests share the same tenant, Nest also supports durable providers — @Injectable({ scope: Scope.REQUEST, durable: true }) — which let the container reuse a request-scoped sub-tree across requests that share a common attribute (like a tenant ID) instead of rebuilding it every single time.

Stage 5: scope bubbling

Scopes aren't isolated to the provider that declares them. If OrdersController injects RequestContextService (request-scoped) directly, OrdersController itself becomes request-scoped — Nest has to create a new controller instance per request too, because it can't build a DEFAULT-scoped controller once and hand it a dependency that only exists per-request. This is called scope bubbling: request scope propagates up the entire chain of things that (directly or transitively) depend on it.

TRANSIENT doesn't bubble the same way. A DEFAULT-scoped service that injects a TRANSIENT logger stays DEFAULT-scoped — it just gets its own private logger instance, created once, same as any other dependency at bootstrap. Transience only means "not shared between different consumers," not "recreated per request."

Key concept: before marking any provider REQUEST-scoped, check what already depends on it. One request-scoped leaf can turn an entire branch of your app — including controllers — into something rebuilt on every single request.

Edge cases and gotchas

Two providers listings, zero shared state. The bug that opened this article. If a "singleton" seems to be losing state, check whether it's registered in more than one module instead of exported from one and imported everywhere else.
Circular provider dependencies. If ServiceA needs ServiceB and ServiceB needs ServiceA, Nest can't decide which to build first. forwardRef(() => ServiceB) on both sides breaks the deadlock — but a true circular dependency between services is usually a sign one of them should be split.
Injecting a request-scoped provider into a DEFAULT-scoped one you don't control (a library service, for instance) silently makes that dependency chain request-scoped too, even though nothing about its own code changed. The bubbling happens at the injection site, not the declaration site.
useFactory dependencies must be listed in inject, in the same order as the factory's parameters. Nest resolves them positionally; a factory that takes (config, logger) but declares inject: [LoggerService, ConfigService] will hand each argument the wrong provider, with no error — just quietly wrong values.
String tokens collide across modules if you're not careful. 'CACHE' in one module and 'CACHE' in another are the same token as far as a shared injector is concerned. Prefer a Symbol() or an app-wide constants file for non-class tokens once you have more than a couple.

Best practices

Default to Scope.DEFAULT. It's the fastest option and correct for the overwhelming majority of providers — anything that doesn't hold per-request state.
Own shared providers in one module, export them, and import that module everywhere else. Never re-declare the same class in two providers arrays as a shortcut.
Reach for REQUEST scope only for data that's truly per-request (the current user, a correlation ID, tenant context) — and remember it will make everything upstream of it request-scoped too.
Reach for TRANSIENT scope only when sharing would actually cause a bug — a logger that should identify its caller is the common case; most services don't need it.
Use string/symbol tokens for anything that isn't a class — config values, third-party clients, interfaces — and keep them in one place so two modules never accidentally collide on the same string.
In tests, override providers rather than constructing real ones. Test.createTestingModule({...}).overrideProvider(CacheService).useValue(fakeCache) swaps a token's resolution for a test double without touching how the rest of the module is wired — it's the exact same token/registration mechanism this article covers, aimed at a test double instead of the real class.

🧠 Test yourself

Think it clicked? Take the 9-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

FAQ

Is a NestJS provider actually a singleton?

Within one registration, yes — DEFAULT scope guarantees one instance for the life of the app for that specific registration. It is not automatically an app-wide singleton if the same class is registered separately in more than one module; that produces multiple, independently "singleton" instances.

How do I get two different instances of the same service on purpose?

Either mark it Scope.TRANSIENT (a fresh instance per consumer), or register it twice under two different tokens using useClass — e.g. { provide: 'PRIMARY_DB', useClass: DbConnection } and { provide: 'REPLICA_DB', useClass: DbConnection }.

Does exporting a provider create a new instance?

No. exports doesn't instantiate anything — it makes an existing registration visible to modules that import the module doing the exporting. The instance is still created once, by whichever module has it in providers.

Why does `@Inject()` show up on some constructor parameters and not others?

Nest can use a class as its own injection token automatically, because TypeScript's type metadata gives it something to match. A string, symbol, or interface token has no runtime type to read, so @Inject('TOKEN') tells Nest explicitly what to resolve.

Does REQUEST scope work the same way in WebSocket gateways and microservices?

Request-scoped providers are supported outside plain HTTP controllers too, but "request" means whatever triggers a handler in that transport (a socket event, a message) — always check that the perf tradeoff still makes sense for a transport that may see much higher throughput than typical HTTP traffic.

Cheat sheet

Need	Syntax	Notes
Basic provider	`providers: [MyService]`	Shorthand for `{ provide: MyService, useClass: MyService }`
Share one instance across modules	Export from an owner module, `imports` it elsewhere	Never re-list the class in a second `providers` array
Provide a plain value	`{ provide: 'TOKEN', useValue: x }`	Needs `@Inject('TOKEN')` at the injection site
Swap implementations	`{ provide: Base, useClass: Impl }`	Consumers still inject `Base`
Build at runtime with deps	`{ provide: 'X', useFactory: fn, inject: [...] }`	`inject` order must match `fn`'s parameter order
Alias an existing token	`{ provide: 'ALIAS', useExisting: Real }`	Same instance, second name
One instance for the app	`@Injectable()` (default)	`Scope.DEFAULT`, built once at bootstrap
One instance per request	`@Injectable({ scope: Scope.REQUEST })`	Bubbles up to every consumer; ~5% latency cost when used narrowly
One instance per consumer	`@Injectable({ scope: Scope.TRANSIENT })`	Doesn't bubble; each injector gets its own copy
Reuse a REQUEST sub-tree by tenant	`@Injectable({ scope: Scope.REQUEST, durable: true })`	Multi-tenant optimization
Override in tests	`Test.createTestingModule().overrideProvider(X).useValue(fake)`	Same token mechanism, aimed at a test double

Key takeaways

A provider's identity in Nest is its token plus its registration — not just its class name. The same class registered in two modules is two instances.
Share one instance by exporting it from a single owning module and importing that module everywhere it's needed — never by listing the class twice.
useValue, useClass, useFactory, and useExisting are four answers to "what does this token resolve to," and non-class tokens need @Inject() because there's no type for Nest to read.
REQUEST and TRANSIENT scope solve real problems, but REQUEST scope bubbles up the entire dependency chain and comes with a real, if usually small, performance cost — reach for DEFAULT unless you specifically need per-request state.

The CacheService bug from the top of this article has a one-line fix — move it into an exported, imported CacheModule — but the DI container doesn't tell you that's the problem. It just quietly builds what you asked for: two registrations, two instances, two counters, both correct on their own and wrong together. Once you're reading "singleton" as "one instance per registration" instead of "one instance in the app," that class of bug stops being a mystery and starts being something you check for on sight.

What's the DI bug that cost you the most time to track down — a duplicate registration, a scope that bubbled somewhere you didn't expect, or something else? Drop it in the comments.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected:

⭐ GitHub — follow me and star the projects: github.com/parsajiravand
💬 Discord — join the frontend best-practices community: discord.gg/d9KRhuAwQ
📸 Instagram — frontend best practices, daily: @bestpractice___

Stop Regex-Parsing document.cookie. Use CookieStore

Parsa Jiravand — Fri, 04 Sep 2026 10:57:34 +0000

Open any codebase old enough to have cookies in it and grep for document.cookie. You will find a function that looks like this, written by someone who is no longer at the company:

function getCookie(name) {
  const match = document.cookie.match(
    new RegExp("(^| )" + name + "=([^;]+)")
  );
  return match ? decodeURIComponent(match[2]) : null;
}

It works. It has worked since 2011. It also has a small, well-known list of ways to get it wrong — cookie names that are prefixes of each other, values with unescaped = or ;, whitespace after the semicolon depending on which browser wrote the header. Everyone's seen at least one of these bugs. Nobody rewrites the function, because it's not broken today.

Here's the harder problem that regex can't fix at all: you have no way to know when a cookie changes. Not from another tab. Not from a Set-Cookie header on a fetch() response. Not even from a second script on your own page calling document.cookie = ... a moment after yours did. document.cookie is a plain string property. Reading it tells you the current state. It has never told you when the state moved.

What everyone reaches for instead

Once the "I need to react to cookie changes" requirement shows up — a login cookie set by an API call, a consent banner another tab just dismissed — the usual fixes are:

Poll document.cookie on an interval. It works, in the sense that a setInterval checking a string every 500ms will eventually notice a change. It also means every tab of every user is now diffing a string forever for an event that might happen once a session.
Have the server tell the client via a WebSocket or SSE. Real infrastructure for a problem that's purely local — the cookie already changed on this machine, in this browser, you just don't have a hook for it.
Wrap every single place that writes a cookie in your own pub/sub. This can work, right up until a third-party script, a Set-Cookie response header, or literally the browser's own cookie-jar expiry logic changes a cookie your pub/sub doesn't know about.

All three treat "the browser won't tell me" as something to engineer around. It's worth asking why the browser won't tell you in the first place — and it turns out, more recently, it will.

The API that actually does this: `cookieStore`

Chrome and Edge ship window.cookieStore (and self.cookieStore inside a service worker) — a promise-based Cookie Store API that treats cookies as structured objects instead of one string you serialize by hand.

Reading is no longer a regex:

const session = await cookieStore.get("session_id");
// { name: "session_id", value: "abc123", domain: null, path: "/", ... } or null

const all = await cookieStore.getAll();
// array of every cookie visible to this document, already parsed

Writing takes an object instead of a hand-built key=value; path=...; expires=... string:

await cookieStore.set({
  name: "theme",
  value: "dark",
  expires: Date.now() + 1000 * 60 * 60 * 24 * 30, // 30 days, in ms
  path: "/",
});

await cookieStore.delete("theme");

And the part document.cookie could never do — a real event:

cookieStore.addEventListener("change", (event) => {
  for (const cookie of event.changed) {
    console.log("set:", cookie.name, cookie.value);
  }
  for (const cookie of event.deleted) {
    console.log("deleted:", cookie.name);
  }
});

That listener fires for cookies your page sets, cookies a fetch() response set via Set-Cookie, and cookies removed by expiry — no polling, no pub/sub you wrote yourself. A consent banner that gets dismissed in one tab can now update every other open tab of the same origin the moment it happens.

🎮 Try it yourself

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

The default that's stricter than you're used to

Here's the thing that actually catches people moving existing code over, and it's not a bug — it's a deliberate spec choice that reads like a footnote until it breaks something.

When you write a cookie the old way, through a Set-Cookie header or document.cookie, and you don't specify SameSite, browsers default it to Lax. That's been true for years — it's why a cookie set on your site still rides along when a user clicks a plain link to your site from somewhere else, but doesn't get sent on a cross-site POST.

cookieStore.set() doesn't inherit that default. Per the spec, if you don't pass sameSite explicitly, it defaults to "strict" — stricter than what document.cookie gives you for free. A Strict cookie is withheld on any cross-site navigation, top-level link clicks included.

So the failure mode looks like this: you migrate a cookie-setting line from document.cookie = "..." to cookieStore.set({...}), run your test suite, ship it. Everything that happens inside your own site keeps working, because same-site requests don't care about SameSite at all. Weeks later, someone clicks a link to your site from an email or a partner site, lands on a page that expects that cookie to already be there, and it isn't. No error. No console warning. The cookie you set is simply not attached to that request, because Strict said not to.

The fix is one keyword, once you know to look for it:

await cookieStore.set({
  name: "session_id",
  value: token,
  sameSite: "lax", // match what document.cookie would have given you
});

Two things worth knowing before you reach for it

It's Chromium-only right now. Chrome and Edge support cookieStore; Firefox and Safari don't ship it as of this writing. Check the current numbers on caniuse before you rely on it for anything that isn't wrapped in a feature check — if ("cookieStore" in window) — with a document.cookie fallback.
It requires a secure context. Like most newer, more capable browser APIs, cookieStore simply isn't there on plain http:// origins outside localhost. If it's undefined in production but present when you test locally, that's almost certainly why.

The takeaway

document.cookie was never designed to be parsed — it's a string interface bolted onto a feature that predates JSON.parse existing. cookieStore treats cookies as the structured, awaitable, observable data they actually are, and the change event alone is worth the migration for anything that needs to react to a cookie set outside your own code. Just don't let sameSite default silently to something stricter than the behavior you were relying on.

Does your codebase still have a hand-rolled cookie parser in it? How old is it, and does anyone remember writing it?

🧠 Test yourself

Think it clicked? Take the 7-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected:

⭐ GitHub — follow me and star the projects: github.com/parsajiravand
💬 Discord — join the frontend best-practices community: discord.gg/d9KRhuAwQ
📸 Instagram — frontend best practices, daily: @bestpractice___

The await That Silently Breaks navigator.clipboard.writeText()

Parsa Jiravand — Thu, 03 Sep 2026 17:23:31 +0000

Someone on your team ships a "Copy invite link" button. It fetches a fresh, single-use link from the API, then copies it to the clipboard so the user can paste it into Slack. Code review is clean. QA clicks it a dozen times. Works every time.

Two weeks later, a support ticket: "I click Copy, I paste into Slack, and I get yesterday's clipboard contents. Not the link." Another ticket, same shape, different user. You can't reproduce it. You click the button forty times in a row and it copies the link forty times.

Here's the detail that breaks the case open, if you know to look for it: every user who hit this had switched to another tab or clicked into another window in the second or two between clicking Copy and the link actually landing on their clipboard. Nothing crashed. No error reached the UI. navigator.clipboard.writeText() just quietly declined to run, and the code never checked.

The fixes that don't touch it

The instinct is to treat it as a normal race condition or a network hiccup:

Add a loading spinner so the user waits for the fetch to finish before clicking. Doesn't help — the bug isn't about clicking too early, it's about what happens after the click, while your code is still awaiting something.
Wrap the write in try/catch and just eat the error. Now it fails the same amount, but silently on purpose instead of silently by accident. Worse, arguably — you've deleted your own evidence.
Retry the write a moment later. If the reason it failed is still true (the document still isn't focused), the retry fails too. If you retry indefinitely, you've built a poller for a permission that has nothing to do with time.

None of these ask the one useful question: why does a browser API that "just copies a string" refuse to run at all?

The real rule: the API only trusts the instant of the click

navigator.clipboard.writeText() is part of the Async Clipboard API, and it enforces something stricter than "the user clicked a button once, somewhere." At the exact moment you call it, the browser wants two things to still be true:

The document has focus. Not "had focus when the click happened" — has it right now, this call, this tick.
The user gesture is still active. Clicks grant a short-lived window of "the user just did something," and that window doesn't wait around forever.

Await literally anything — a fetch() for the link, a promise chain, even a couple of re-renders — and you've inserted a gap between the click and the actual writeText() call. If the user alt-tabs, clicks a browser chrome element, or a dev-tools panel steals focus during that gap, the call arrives with the document unfocused. The browser doesn't queue it, doesn't warn the user, doesn't retry. It rejects the promise with a NotAllowedError — in Chrome, literally "Failed to execute 'writeText' on 'Clipboard': Document is not focused." — and if nothing in your code reads that rejection, it vanishes into an unhandled-promise-rejection log line nobody watches production for.

// looks completely reasonable, fails silently under real-world timing
async function copyInviteLink() {
  const res = await fetch("/api/invite-link"); // <- the gap opens here
  const { url } = await res.json();
  await navigator.clipboard.writeText(url);    // <- and this is what falls in it
}

Nothing here is wrong syntax. It's wrong sequencing — the write happens whenever the network happens to resolve, not while the click is still fresh.

🎮 Try it yourself

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

The fix: give the API the gesture immediately, the data later

writeText() is a convenience method — it only accepts a string you already have in hand, right now. But its sibling, navigator.clipboard.write(), takes a ClipboardItem, and a ClipboardItem's data doesn't have to be a plain string or Blob. It can be a Promise that resolves to one later. That's the actual tool for "I have the user's permission right now, but not the text yet":

// call write() synchronously, in the same tick as the click —
// the *data* is allowed to arrive whenever it's ready
function copyInviteLink() {
  const linkPromise = fetch("/api/invite-link")
    .then((res) => res.json())
    .then(({ url }) => new Blob([url], { type: "text/plain" }));

  return navigator.clipboard.write([
    new ClipboardItem({ "text/plain": linkPromise }),
  ]);
}

The write() call itself still happens inside the click handler, before any await has had a chance to let focus slip — so the permission check passes at the one moment it's guaranteed to be true. The browser holds the clipboard slot open and fills it in once your promise settles. Nothing about your fetch logic has to change; only which method you hand the eventual string to.

Two details worth knowing before you ship this

The whole API requires a secure context. navigator.clipboard simply isn't there on plain http:// origins (outside localhost) — if it's undefined in production but not on your machine, that's almost always why.
document.execCommand("copy") is deprecated, per MDN, and not guaranteed to work or even exist in every browser going forward. It's still floating around in older code because it predates the Async Clipboard API and doesn't have this exact focus problem — it copies synchronously from a selection, no promise involved — but it's not the thing to reach for in new code, deprecated fallback or not.

The one thing worth remembering

A copy button that works in every manual test and fails for real users isn't flaky — it's timing-dependent in a way your test never reproduces, because you never alt-tab mid-click when you're the one testing it. The rule is simple once you name it: keep the call to the Clipboard API synchronous with the gesture that authorizes it, and if the data isn't ready yet, hand the API a promise instead of making it wait for one.

Have you shipped a copy-to-clipboard button that "just doesn't work sometimes" and quietly caught the error instead of asking why? What did the try/catch look like?

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected:

⭐ GitHub — follow me and star the projects: github.com/parsajiravand
💬 Discord — join the frontend best-practices community: discord.gg/d9KRhuAwQ
📸 Instagram — frontend best practices, daily: @bestpractice___

You're not quiet in meetings, you're editing

Parsa Jiravand — Wed, 02 Sep 2026 10:58:22 +0000

👋 I'm Parsa Jiravand — I work in IT, and this is Best Practice. One article every day, one soft-skills episode every week. It all lives at bestpractic.org — come join us.

It's minute twelve of a fifty-minute meeting and you've got the thing. It's good. It's actually the thing nobody in the room has said yet. You just want to tidy it up a bit so it comes out right.

Minute nineteen: someone else says about two-thirds of it, worse, and everyone nods.

Minute fifty: you're making tea, delivering the full polished version to yourself, and it is genuinely better than what they said, and it does not matter even slightly.

What's actually going on

You've probably decided this is a confidence problem. I don't think it is, mostly.

Watch what the people who talk a lot are actually doing. They're not delivering finished thoughts. They're thinking out loud — starting a sentence before they know how it ends and steering it while it's already moving. A decent chunk of what they say is wrong, and they correct it themselves three sentences later, and nobody holds it against them, because that's what the room is for.

You're doing a different thing. You're drafting. Writing the sentence in your head, checking it, cutting the weak clause, checking again that it doesn't sound stupid — and then submitting it.

Those are two different activities, and only one of them fits inside a meeting.

That's the whole gap. It isn't that they're sharper. It's latency. They're running at conversation speed because they've offloaded the thinking into the talking; you're running at writing speed because you're doing the thinking first, in private, to a higher standard than the format requires.

And here's the mean part. A good thought delivered late arrives worse than a rough one delivered on time. At minute twelve, your half-formed version steers the discussion — it's cheap, it's part of the flow, someone builds on it. At minute thirty, the exact same words are a rewind. You're asking eight people to go back. So now it does have to be brilliant, because you're spending everyone's time to say it. Which makes you edit harder. Which makes it later.

The other thing, and I think this is the one people genuinely don't notice: you're waiting for a gap, and there is no gap. Silence in a meeting isn't an invitation. It's someone breathing in. The people who get to speak aren't luckier with timing — they start on the in-breath, before it's fully quiet. If you're waiting for a clean, unambiguous, obviously-yours window, you can sit through an entire hour without getting one and conclude afterwards that nobody let you in.

So what do you actually say?

Claim the floor before the thought is finished.

The move is to spend your thinking time out loud instead of before. Which sounds horrifying, so you buy the first few seconds with a phrase that requires no content at all:

"Can I jump in on that one?"

That's four seconds of runway, and in those four seconds you form the sentence you were going to form anyway. You never needed to be finished. You needed to not be silent while you finished.

Label it half-formed and it stops having to be right.

"Half-formed thought — is this the same problem as the thing with the billing sync?"

Two things happen there. The label sets the terms: you've told the room this is a draft, so nobody's grading it as a conclusion. And it's a question, which is a complete contribution even when your opinion isn't ready — it moves the discussion without requiring you to be correct about anything.

That second part matters more than it sounds, because most of the reason people stay quiet is that they're waiting to have an answer. You almost never need an answer. Naming the thing everyone is circling is a contribution: "Are we deciding this now, or are we working out who decides it?" has saved more meeting-hours than any opinion I've seen delivered.

Say something in the first ten minutes. Anything.

Not a good thing. Any thing. "Can we go back one slide?" counts.

The mechanic is that the room builds a model of you early — participant or audience — and every minute of silence after that raises the price of your first sentence. At minute three, speaking is nothing. At minute forty, speaking means visibly changing category in front of everyone, which is a far bigger move than the one you were avoiding. People read your first contribution as your register for the meeting. Nobody notices the second one at all.

And the one that does the most work: get in before the meeting.

One line to whoever's running it, the day before: "I've got a thing about the migration — want me to raise it, or is that not this meeting?"

Now you're expected. Being expected is most of being able to speak, because the hard part was never the sentence — it was granting yourself permission to take the room's time, and someone else has now granted it for you. And maybe a third of the time you'll get back "oh, we actually settled that on Friday," which saves you the entire ordeal.

One thing that's new this year

If your company runs an AI notetaker — and most do now — something is true that wasn't a few years ago. The summary lists decisions, owners, and who raised what. It gets skimmed by people who weren't there. It is the version that survives.

Which means the mediocre thing you said out loud at minute twelve is in the record, and the excellent version you sent in a DM afterwards isn't. I'm not thrilled about that either. But it's an argument for the cheap early sentence, not against it.

Worth knowing the other half: those summaries get attribution wrong reasonably often, and there's no appeals process. So if something genuinely needs to be yours, a comment on the doc beforehand is more durable than a spoken line — it's timestamped, it's written down, and it's still there when the transcript decides someone else said it.

Where this backfires

If you're the most senior person in the room, invert all of it. Speaking early doesn't make you a participant, it closes the question — you'll get agreement instead of opinions and you won't be able to tell which one you got. Your version of this is to go last, and to leave a silence long enough to be uncomfortable, and then to hold it, because the useful thing in that room isn't coming from you.

Second: don't do it to be seen doing it. Talking to appear engaged is one of the most legible things a person can do — nobody can prove it, everybody clocks it. If you speak early and it's filler, you've just spent the credibility you were trying to build. "Any thing" means any real thing. "Can we go back a slide" is real. Confidently restating what the last person just said is not.

Third, and this one depends entirely on the room: in some teams, and in some cultures, jumping in is straightforwardly rude, and the actual protocol is the raised hand, or the chat, or waiting to be asked by name. Advice about interrupting is mostly written by people who work in rooms where interrupting is free. Spend one meeting watching how contributions actually get in — that's a real thing to do with a meeting — then use that door instead of this one.

The part that isn't fair

Interrupting is not equally priced.

The same jump-in reads as decisive from one person and rude from another, and it has very little to do with the sentence. If you're the only junior in there, if you're dialled in while five people share a room, if you're the only woman at the table, if you're working in your second language — you are paying more per interruption than the person next to you. Every article that says "just speak up more" is quietly assuming your price is the same as the author's.

The remote one is partly literal, which I find weirdly comforting. A few hundred milliseconds each way means you physically cannot land in a pause — by the time the silence reaches you and your voice gets back, the room has moved. You're not being hesitant. You're behind by a measurable amount of time.

Two honest responses to that. The first is that whoever runs the meeting can fix it in one sentence — "let's go round" or "hang on, Sam had something" — and most of them will, if you ask once, privately, in plain words: "I keep getting talked over on the call. Could you come to me by name?" That's not a complaint, it's a request with a mechanism, and it's much easier to say yes to.

The second is that writing is a legitimate route and not the consolation prize. A comment on the doc lands in the room whether you speak or not. Some people are simply better in writing, and building your influence around that is a strategy rather than a surrender. The trap is that it only works before. The same paragraph posted after the meeting is a note. Posted the night before, it's the agenda.

And the last uncomfortable thing, which took me a long time to see: a lot of decisions weren't made in the meeting at all. Two people talked on Tuesday, and the meeting is where it gets said out loud with everyone present. If you keep bringing good arguments that don't move anything, you may not be bad at meetings — you may be arriving at the ratification. The room to change it was the conversation before it, and getting into that conversation is a different skill entirely. One for another week.

Monday

Next meeting you're in, say something in the first five minutes.

It does not have to be good. A question counts. "Can we go back one slide" counts. You're not trying to contribute yet — you're changing category from audience to participant while it's still cheap.

Then for the meeting after that one, send the line the day before: "I've got a thing about X — want me to raise it, or is that not this meeting?"

That's the whole practice. You don't need to become more confident. You need to stop editing and start talking at the same speed as everyone else in the room.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected:

⭐ GitHub — follow me and star the projects: github.com/parsajiravand
💬 Discord — join the frontend best-practices community: discord.gg/d9KRhuAwQ
📸 Instagram — frontend best practices, daily: @bestpractice___

🤝 Want to make something with us? Write a piece, come on the podcast, or bring an idea that should exist — bestpractic.org/collaborate.

And if this one helped, send it to the person you know who needs it this week. That's what keeps these coming.

Shadow DOM Needed JavaScript to Exist. Now It Doesn't.

Parsa Jiravand — Wed, 02 Sep 2026 10:57:52 +0000

You curl your own page. The one with the fancy web component — the accordion, the tabs, whatever you built to be reusable everywhere. You SSR'd it. You're proud of it. You grep the response for the text inside it.

It's not there.

What's there instead is a custom element with nothing inside it, and if you squint at the raw HTML you might spot a <template> tag nearby, doing nothing. The content — the styled, encapsulated, actually-rendered thing a user sees — doesn't exist yet. It shows up a beat later, after JavaScript runs, which on a slow connection or a busy main thread is long enough to see the host element sit empty, then pop.

Here's the part that takes people longer to accept than it should: this was never a bug in your SSR setup. Shadow DOM itself had no way to be server-rendered. Not "hard" — structurally absent.

The obvious fixes that don't touch the real problem

The instinct, once you notice the flash, is to attack it like a loading-performance problem:

Inline the critical CSS so at least the page doesn't flash unstyled. Doesn't help — the shadow tree's content isn't unstyled, it's absent. There's nothing to style yet.
Defer less, preload the script earlier. Shaves milliseconds. The gap doesn't close, it shrinks — and on a throttled connection or a busy tab it's still visible.
Skeleton-load it, show a placeholder shape until hydration. This works, and it's honestly the standard answer today — but notice what you just admitted: you're not server-rendering the component, you're server-rendering an apology for the component and rendering the real thing later, client-side, same as if you'd shipped no HTML at all.

All three treat the symptom. None of them explain why a server-rendered custom element can serialize its attributes and its light-DOM children into HTML, but not its shadow tree.

The real diagnosis: there was no way to write it down

element.attachShadow({ mode: "open" }) is a method call. It runs in JavaScript, against a live DOM node, in a live document. There has never been an HTML syntax for "this element has a shadow root containing this markup" — the shadow tree simply doesn't exist as text you can send over the wire. A server can stringify your component's attributes and its regular children all day. The encapsulated part — the actual point of using Shadow DOM — has nowhere to go in that string.

So "server-rendered web component" quietly meant: server-rendered light DOM, client-attached shadow DOM, and a component that isn't really done rendering until JavaScript shows up and calls a method. For a design system trying to sell itself on being framework-agnostic and usable anywhere — including a no-JS environment, a crawler, or a slow device — that's a real gap, not a nitpick.

The fix: give the parser something to attach

Declarative Shadow DOM closes the gap by teaching the HTML parser a new trick instead of teaching JavaScript a new one. Put a <template> with a shadowrootmode attribute as the first child of an element, and the parser attaches its contents as a real, live shadow root the instant it finishes reading the closing tag — before any <script> further down the page has run:

<!-- the old way: an empty host, waiting for JS -->
<my-badge></my-badge>
<script>
  customElements.get("my-badge") ||
    customElements.define("my-badge", class extends HTMLElement {
      connectedCallback() {
        this.attachShadow({ mode: "open" }).innerHTML =
          `<style>span{color:hotpink}</style><span>New</span>`;
      }
    });
</script>

<!-- the new way: the shadow root exists the moment HTML parses -->
<my-badge>
  <template shadowrootmode="open">
    <style>span { color: hotpink; }</style>
    <span>New</span>
  </template>
</my-badge>

No script needed to make the second version render — document.querySelector("my-badge").shadowRoot is already non-null before your JavaScript has had a chance to run at all. If you do still want to progressively enhance it with a custom element class, that's fine: attach-shadow-if-not-already-attached is the standard guard, since a browser that already declaratively created the shadow root won't create a second one for you.

A couple of details worth knowing before you reach for it:

shadowrootmode is "open" or "closed", mirroring attachShadow()'s mode option — "closed" still renders the content, it just means element.shadowRoot returns null to outside script, same as the imperative API.
Only the first matching <template> counts. If a parent already got a declarative shadow root, a second shadowrootmode template in the same position is left alone as a plain, inert <template> element rather than throwing — a browsers-are-forgiving default, but not one to rely on if you're generating this HTML yourself.
Round-tripping it needs an extra flag. If you want to read a component's current shadow content back out as a string (say, to re-serialize it after a client-side update), add shadowrootserializable to the template and call getHTML({ serializableShadowRoots: true }) — without it, outerHTML and friends skip shadow content entirely, same as before.

🎮 Try it yourself

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

Where it stands today

This isn't a "wait five years" feature. Declarative Shadow DOM is Baseline: Chrome and Edge since version 111 (with the full attribute set standardized by 124), Firefox since 123, Safari since 16.4. If your SSR framework or web component library doesn't emit shadowrootmode templates yet, that's a library gap, not a browser one — and it's worth filing an issue instead of writing another skeleton loader.

The one thing worth remembering

An empty custom element with a <template> next to it isn't broken HTML — it's HTML written for a browser that hasn't decided to help yet. Declarative Shadow DOM is the browser deciding to help: the parser does at read-time what a <script> tag used to have to do at run-time, and the gap between "the server sent HTML" and "the component actually rendered" gets to close for good.

Do you SSR web components today — and if so, are you shipping the skeleton-loader workaround or has your framework already picked this up? I'd like to know which libraries got there first.

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected:

⭐ GitHub — follow me and star the projects: github.com/parsajiravand
💬 Discord — join the frontend best-practices community: discord.gg/d9KRhuAwQ
📸 Instagram — frontend best practices, daily: @bestpractice___

Next.js Cache Components Explained (with Cheat Sheet)

Parsa Jiravand — Tue, 01 Sep 2026 11:24:14 +0000

You add one line to a layout — const theme = (await cookies()).get('theme')?.value — to greet returning visitors by their saved preference. Nothing else changes. Deploy, and your blog's server load quadruples: every page that used to serve instantly from a CDN edge now renders fresh, on your origin server, for every single visitor, including the 95% of the page that is identical for everyone.

Nothing you wrote was wrong, exactly. It's how the App Router's previous rendering model worked: one dynamic API call anywhere in a route's tree marked the entire route dynamic. Next.js's new Cache Components model exists specifically to fix this, and understanding how it decides what's static, what's cached, and what streams is the single most valuable thing you can know about the framework right now.

What you'll learn

By the end of this article you'll be able to:

Explain why a single cookies() or headers() call used to make a whole Next.js route dynamic, and how Cache Components changes that
Use the use cache directive at the function, component, and file level, and know which one to reach for
Set explicit cache lifetimes with cacheLife and invalidate on demand with cacheTag + updateTag
Read a route and predict which parts become the static shell, which get cached, and which stream in behind a <Suspense> boundary
Avoid the constraints that trip people up first: reading runtime APIs inside a cached scope, and passing uncached promises into one

Who this is for

You've built at least a small App Router project — a page.tsx, a layout.tsx, maybe a fetch call inside a Server Component. You don't need any prior experience with caching APIs; we build the model from nothing.

This article is written against Next.js 16.3 (verified against the framework's own documentation and npm's latest dist-tag in August 2026). Cache Components shipped as an opt-in flag in Next.js 16.0 and is the model this article teaches; where the still-supported previous model (implicit fetch caching, route segment configs like export const dynamic) differs, it's called out explicitly rather than left implied.

The problem: one cookie read, one fully dynamic page
The mental model: pieces decide, not routes
Stage 1: turning it on
Stage 2: caching data with use cache
Stage 3: caching a component, and reading cacheLife
Stage 4: the part that can't be cached — Suspense
Stage 5: invalidating on demand with cacheTag
Edge cases and gotchas
Best practices
FAQ
Cheat sheet

The problem: one cookie read, one fully dynamic page

Here's a blog layout that reads a saved theme preference so it can render the right class on <body>:

// app/layout.tsx — pre-Cache-Components App Router
import { cookies } from 'next/headers';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const theme = (await cookies()).get('theme')?.value ?? 'light';
  return (
    <html lang="en">
      <body className={theme}>{children}</body>
    </html>
  );
}

cookies() is a request-time API — it can only produce a value once an actual request exists, so there's no way to know it at build time. In the App Router's previous rendering model, that fact wasn't scoped to the component that called it: reading a dynamic API anywhere in a route's component tree opted the entire route out of static rendering. The header, the article body, the footer, the "10 related posts" list that's the same for every visitor — all of it now re-renders on the server, on every request, because one <body> class needed to know something about the current user.

You can work around this in the previous model (extract the theme read into a small Client Component that reads document.cookie after hydration, for instance), but the workaround is the tell: the framework's default behavior didn't distinguish "this one value needs live data" from "this route needs live data." Cache Components draws that line at the component, not the route.

The mental model: pieces decide, not routes

The mental model: in the previous model, a route got one verdict — static or dynamic — decided by the most demanding thing anywhere in its tree. With Cache Components enabled, that verdict moves down to individual functions and components. Each one is either cached (with an explicit lifetime), streamed behind a <Suspense> boundary, or — if it does neither and touches something request-specific — flagged by the framework as needing one of those two treatments before the build will pass.

Next.js still produces one artifact per route: a static shell, prerendered at build time, containing every static and cached piece plus fallback UI for anything still streaming. That shell is what a CDN can serve instantly on a direct visit. The pieces behind <Suspense> fill in afterward, at request time, without dragging the rest of the page down with them.

Stage 1: turning it on

Cache Components is an opt-in flag as of Next.js 16.0 — a fresh create-next-app project doesn't enable it by default yet:

// next.config.ts
import type { NextConfig } from 'next';

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

export default nextConfig;

Key concept: this one flag replaces three separate experimental flags from Next.js 15 (dynamicIO, useCache, and ppr) with one unified setting, and it requires the Node.js runtime — routes still exporting the deprecated runtime = 'edge' need to migrate first.

Stage 2: caching data with `use cache`

The use cache directive marks an async function's or component's return value as cacheable. Start with a plain data-fetching function:

// app/lib/posts.ts
import { cacheLife } from 'next/cache';

export async function getRecentPosts() {
  'use cache';
  cacheLife('hours');
  const res = await fetch('https://api.example.com/posts');
  return res.json();
}

The first call with a given set of inputs runs the function and stores the result; every later call with the same inputs — including different requests, from different visitors — reuses it, until the lifetime you set with cacheLife expires. Arguments and any variables captured from an outer scope become part of the cache key automatically, so getRecentPosts(category) called with two different categories gets two separate cache entries.

Key concept: use cache caches a result, keyed by its inputs — not a route, not a URL. That's what lets a component ten levels deep cache independently from everything around it.

Stage 3: caching a component, and reading `cacheLife`

The same directive works at the component level, caching everything the component renders:

// app/blog/recent-posts.tsx
import { cacheLife, cacheTag } from 'next/cache';

export async function RecentPosts() {
  'use cache';
  cacheLife('hours');
  cacheTag('posts');

  const res = await fetch('https://api.example.com/posts');
  const posts: { id: string; title: string }[] = await res.json();

  return (
    <ul>
      {posts.map((p) => (
        <li key={p.id}>{p.title}</li>
      ))}
    </ul>
  );
}

cacheLife('hours') isn't a made-up duration — it's one of six built-in profiles, each balancing three numbers: how long the client trusts a cached copy without checking (stale), how often the server regenerates it in the background (revalidate), and when it's dropped entirely if nobody's asked for it (expire). Omit cacheLife and the default profile applies implicitly — which works, but leaves the lifetime invisible at the call site. Naming it explicitly is the recommended habit.

If this result is part of what could go into the route's prerendered static shell (its stale window is long enough), it's filled in at build time and served straight from a CDN on a direct visit — no server round trip at all.

Stage 4: the part that can't be cached — Suspense

Back to the theme example. The fix isn't to avoid cookies() — it's to contain it:

// app/layout.tsx — with Cache Components
import { cookies } from 'next/headers';
import { Suspense } from 'react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Suspense fallback={null}>
          <ThemeBody>{children}</ThemeBody>
        </Suspense>
      </body>
    </html>
  );
}

async function ThemeBody({ children }: { children: React.ReactNode }) {
  const theme = (await cookies()).get('theme')?.value ?? 'light';
  return <div className={theme}>{children}</div>;
}

RootLayout itself no longer awaits cookies(), so it isn't request-dependent, and it completes during prerendering. ThemeBody is the only thing that streams in at request time — the header, the article body, and everything else in children that's cached or static ships in the initial shell exactly as before. One component's need for live data no longer taxes the whole page.

Key concept: <Suspense> doesn't make a component dynamic — it gives a component that's already dynamic (because it reads a runtime API, or fetches without caching) somewhere to put its fallback so the rest of the shell doesn't have to wait for it. A component that only does synchronous work completes during prerendering regardless of whether it's wrapped.

Stage 5: invalidating on demand with `cacheTag`

Time-based expiry (cacheLife) and on-demand invalidation (cacheTag) aren't alternatives — they're usually paired. RecentPosts above tagged its cache entry 'posts'. When a new post is published, invalidate every entry with that tag, from anywhere the mutation happens:

// app/actions.ts
'use server';

import { updateTag } from 'next/cache';

export async function publishPost(formData: FormData) {
  await db.posts.create({ /* ... */ });
  updateTag('posts'); // every 'posts'-tagged cache entry is now stale
}

This is the same pattern as the older revalidateTag, but updateTag is aware of Cache Components' server and client caches together, so tagging and invalidating stays a single mental step regardless of which layer actually stored the result.

🎮 Try it yourself

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

Edge cases and gotchas

A cached scope can't read runtime APIs at all. Calling cookies(), headers(), or reading searchParams directly inside a use cache function — or inside anything it calls — throws. Read the value in an uncached component first, then pass it as an argument to the cached function; the argument becomes part of the cache key.
Passing an uncached promise into a cached function hangs the build. If a use cache function awaits a promise that resolves to request-specific or otherwise-uncached data (received as a prop, from a closure, or from shared storage like a Map), the build waits for data that can never resolve during prerendering and times out after 50 seconds. Await the value outside the cached scope and pass the resolved value in.
Math.random(), Date.now(), and crypto.randomUUID() need an explicit choice. They produce a different value every call, so Cache Components requires you to say what you mean: call connection() before them and wrap in <Suspense> to get a genuinely unique value per request, or wrap them in use cache so every visitor sees the same value until it revalidates.
Serialization has real limits. Arguments and cached return values must be serializable — primitives, plain objects, arrays, Date/Map/Set, and (for return values only) JSX. Class instances, functions, and URL instances aren't allowed, except as opaque pass-through props like children.
Draft Mode bypasses the cache entirely. With Draft Mode enabled, every cached function re-executes on every request and nothing is written to the cache — by design, so preview content is never stale.
Bots and crawlers skip the shell. Because they need a complete document, Next.js detects them by user agent and renders the whole page dynamically at request time instead of serving the static shell. If any part of your shell depends on build-time-only data, make sure the same data is reachable at request time too, or a page that renders for a person can fail for a crawler.

Best practices

Push runtime API reads as deep into the tree as they'll go. A params or cookies() read at the top of a layout blocks everything below it from being static; the same read three components down blocks only that subtree. The deeper the dynamic work sits, the more of the page prerenders.
Pair every use cache with an explicit cacheLife. The implicit default profile (5-minute stale, 15-minute revalidate, never expires) works, but naming the profile you actually mean documents the decision at the call site.
Reach for cacheTag + updateTag for anything invalidated by a mutation, and a longer cacheLife (days, weeks, or max) for content that only changes when someone edits it — the two together mean you rarely need a short polling-style lifetime.
Don't cache what should stream. A component that genuinely needs the current request — a cart total from a session cookie, a personalized recommendation — belongs behind <Suspense>, not squeezed into a cache with an artificially short lifetime.
use cache: private is the exception, not the default. It exists for cases where you can't refactor to pass runtime data as arguments; reach for it rarely, since regular use cache plus an extracted argument covers most real cases and stays easier to reason about.

FAQ

Do I have to enable `cacheComponents` to use Next.js 16?

No. It's an opt-in flag. Without it, your app uses the previous rendering model — fetch requests are uncached by default (a change from Next.js 14), and route segment configs like export const dynamic and revalidate still work exactly as before.

Does Cache Components replace `revalidatePath`?

Not entirely — revalidatePath still exists for the previous model's route-level cache. Inside Cache Components, prefer cacheTag plus updateTag (or revalidateTag), which target specific cached results by tag rather than an entire route.

Is Cache Components the same thing as Partial Prerendering (PPR)?

Related, not identical. Partial Prerendering — a static shell plus streaming holes — is the rendering behavior Cache Components implements by default. cacheComponents: true is the single flag that turns PPR on along with use cache and the removal of implicit dynamic-API-triggers-whole-route behavior; you no longer set an experimental PPR flag separately.

Does `use cache` persist across deployments?

No. Every cache key includes the build ID (or your configured deploymentId), so a new deploy starts with an empty cache, even for the durable use cache: remote variant. That's deliberate — it guarantees a deploy never serves output built from stale code.

What happens if I forget `cacheLife` on a `use cache` function?

Nothing breaks — the default profile applies (5-minute client-side stale window, 15-minute server-side revalidate, no time-based expiry). The framework recommends setting it explicitly anyway, since the alternative is a lifetime that's easy to lose track of.

Cheat sheet

Task	Code	Notes
Enable Cache Components	`cacheComponents: true` in `next.config.ts`	Requires Node.js runtime
Cache a data function	`'use cache'` at the top of an async function	Result keyed by arguments + captured closures
Cache a whole component	`'use cache'` at the top of an async component	Composed `children`/slots pass through uncached
Cache every export in a file	`'use cache'` at the top of the file	Every exported function must be async
Set an explicit lifetime	`cacheLife('hours')`	One call per function invocation, inside the cached scope
Tag a cache entry	`cacheTag('posts')`	Pairs with `updateTag`/`revalidateTag`
Invalidate on demand	`updateTag('posts')` inside a Server Action	Invalidates every entry with that tag
Stream request-specific data	Wrap in `<Suspense fallback={...}>`, read `cookies()`/`headers()` inside	Fallback ships in the static shell; content streams at request time
Get a unique value per request	`await connection()` then `Math.random()`/`Date.now()`, inside `<Suspense>`	Forces request-time evaluation instead of a cached build-time value

// The pattern in one page: static, cached, and streaming together
import { Suspense } from 'react';
import { cookies } from 'next/headers';
import { cacheLife, cacheTag } from 'next/cache';

export default function BlogPage() {
  return (
    <>
      <header>Static — prerendered automatically</header>
      <RecentPosts />{/* cached, joins the static shell */}
      <Suspense fallback={<p>Loading your preferences…</p>}>
        <UserPreferences />{/* streams in at request time */}
      </Suspense>
    </>
  );
}

async function RecentPosts() {
  'use cache';
  cacheLife('hours');
  cacheTag('posts');
  const posts = await fetch('https://api.example.com/posts').then((r) => r.json());
  return <ul>{posts.map((p: any) => <li key={p.id}>{p.title}</li>)}</ul>;
}

async function UserPreferences() {
  const theme = (await cookies()).get('theme')?.value ?? 'light';
  return <aside>Theme: {theme}</aside>;
}

Key takeaways

The previous App Router model gave each route one verdict — static or dynamic — decided by its most demanding component. Cache Components moves that decision down to individual functions and components.
use cache caches a result by its inputs; pair it with an explicit cacheLife so the lifetime is visible at the call site, not implicit.
<Suspense> is how a genuinely request-specific piece streams in without dragging the rest of the page's caching down with it — it doesn't make a component dynamic, it gives one that already is somewhere to put its fallback.
Time-based (cacheLife) and on-demand (cacheTag + updateTag) revalidation are complementary, not competing — most real content wants both.
The line between "this needs live data" and "this route needs live data" is now drawn at the component, and that's the whole point.

Back to that layout

The fix for the theme cookie wasn't to stop reading it — it was to stop letting one read decide the fate of everything around it. Move the read into its own component, wrap it in <Suspense>, and the header, the article, and the "related posts" list go back to shipping from the edge, instantly, while the one thing that actually needed to know who's visiting still gets to ask.

If you want the background this article assumes — what a Server Component actually is and why "it's just SSR" is the wrong mental model — Server Components Without the Hype covers that half, and this article picks up from there.

What's the last route you had to manually pull out of "fully dynamic" — and did you know at the time which single line caused it?

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected:

⭐ GitHub — follow me and star the projects: github.com/parsajiravand
💬 Discord — join the frontend best-practices community: discord.gg/d9KRhuAwQ
📸 Instagram — frontend best practices, daily: @bestpractice___

Your Router Doesn't Intercept Navigation. It Reacts To It.

Parsa Jiravand — Tue, 01 Sep 2026 11:23:43 +0000

Click a link. Before the new page finishes loading, click a different one. You'd expect the second click to win — that's what happens with a plain <a href> and a full page load. In a lot of single-page apps, it doesn't.

What actually happens: the first navigation starts fetching data. The second navigation starts too. Whichever fetch resolves last wins, regardless of which link you clicked last. For a second, the URL bar says one page and the rendered content says another. On a slow connection, "for a second" can be long enough for someone to screenshot it and file a bug titled "app shows wrong page."

Here's the part that surprises people: this isn't a bug in your router. It's the shape of the tool.

How `pushState` routing actually works

Every client-side router — the ones you've built by hand and the ones bundled into frameworks — is doing roughly this:

document.addEventListener("click", (e) => {
  const link = e.target.closest("a");
  if (!link || !isInternal(link)) return;

  e.preventDefault();
  history.pushState({}, "", link.href);
  renderRoute(link.href); // fetch data, swap the view
});

window.addEventListener("popstate", () => {
  renderRoute(location.href); // back/forward button
});

Read that again and notice what's missing: nothing here knows about the previous renderRoute call while a new one starts. pushState already changed the URL by the time renderRoute begins — the navigation, as far as the browser's history is concerned, already happened. Your router isn't intercepting it. It's reacting to something already committed, then racing its own async work against whatever the last reaction was doing.

That's the double-click bug in one sentence: two renderRoute calls, no relationship between them, last one to finish wins. Add a canceled fetch and an AbortController to the mix and you can make it mostly go away — mature router libraries do exactly that. But you're patching a race condition from outside the event that caused it, because the click handler and the URL change were never one atomic thing to begin with.

The API built to fire before the URL changes

The Navigation API exists specifically to close that gap. Instead of listening for popstate after a change, you listen for navigate on window.navigation — and that event fires before the browser commits to the new URL, for every kind of navigation: link clicks, back/forward, history.pushState, even form submissions.

navigation.addEventListener("navigate", (event) => {
  if (!event.canIntercept) return; // e.g. cross-origin navigations can't be

  const url = new URL(event.destination.url);

  event.intercept({
    async handler() {
      await renderRoute(url); // the browser waits on this
    },
  });
});

intercept() is the piece popstate never had: it hands the browser a promise and the browser waits on it before treating the navigation as finished — no spinner state you have to fake, no separate "is this route still current" flag to check by hand. And because every navigate event carries its own event.destination, a second click firing a second navigate event doesn't need to guess whether an earlier one is still in flight — you can call event.signal (an AbortSignal the browser aborts automatically when a newer navigation supersedes this one) inside your handler and pass it straight to fetch:

event.intercept({
  async handler() {
    const data = await fetch(url, { signal: event.signal }).then(r => r.json());
    render(data);
  },
});

Click a second link before the first handler resolves, and the browser aborts the first navigation's signal for you. The stale fetch throws, you skip rendering it, and there's no manual bookkeeping to get wrong — the race condition isn't patched, it's structurally not possible to hit.

What you get that `pushState` never gave you

A few things fall out of treating navigation as one interceptable event instead of a click handler plus a popstate listener bolted on the side:

One event for everything. Link clicks, back/forward, and programmatic navigation.navigate() calls all go through the same navigate event — you're not maintaining a click handler and a separate popstate handler that have to agree with each other.
Cancellation that's actually cancellation. event.preventDefault() on navigate stops the navigation before the URL changes, not after — useful for "you have unsaved changes" guards that used to require faking the URL back with another pushState call.
Real navigation state. navigation.currentEntry, navigation.entries(), and events like navigatesuccess / navigateerror give you a queryable list of history entries with keys and state, instead of history.length (a number that tells you nothing about what's in the stack).

None of this replaces routing logic — you still decide what URL maps to what view. It replaces the part where the browser's actual navigation and your app's idea of navigation are two loosely-synced systems held together by preventDefault and hope.

Where it stands today

The Navigation API has shipped in Chrome and Edge since 2022. Safari and Firefox don't have it yet as of this writing, which is the honest caveat: this isn't a drop-in replacement for your router today, and any production use needs a fallback path (or a router library that already detects and uses it under the hood, falling back to pushState where it's missing). Check current support before reaching for it directly in anything beyond a Chromium-only tool.

🎮 Try it yourself

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

The one thing worth remembering

popstate tells you a navigation happened. navigate tells you one is about to, and lets you decide what "happened" even means. That difference is the whole reason the double-click race exists in the first place — and the whole reason it stops existing once the browser is holding the promise instead of you holding a flag.

Next time your router's navigation logic starts growing isNavigating booleans and manual AbortController bookkeeping, that's usually this gap showing through. Have you hit the double-navigation race in production, or did your router already paper over it? I'd like to know which libraries got this right early.

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected:

⭐ GitHub — follow me and star the projects: github.com/parsajiravand
💬 Discord — join the frontend best-practices community: discord.gg/d9KRhuAwQ
📸 Instagram — frontend best practices, daily: @bestpractice___

Debounce and Throttle in JavaScript: The Complete Guide

Parsa Jiravand — Mon, 31 Aug 2026 13:12:13 +0000

Type "javascript" into an unthrottled search box and watch the network tab: an HTTP request for j, another for ja, another for jav, ten in total, nine of them thrown away before the response even lands. The server did ten times the work the feature needed, and the UI flickers with results for a query the user abandoned two keystrokes ago. The fix is two small, deceptively simple functions — debounce and throttle — and the part that trips people up isn't writing them, it's knowing exactly when each one fires.

What you'll learn

By the end of this guide you'll be able to:

Explain the precise difference between debounce and throttle, not just "they both slow things down"
Write a correct debounce and a correct throttle from scratch, including leading/trailing edge behavior
Choose the right one for search inputs, scroll handlers, resize handlers, and button clicks
Avoid the memory leaks and stale-closure bugs both patterns cause in React and vanilla JS alike
Use a copy-paste utility with cancel() and flush() support

Who this is for: you write JavaScript day to day, you've attached an event listener before, and you've either hand-rolled a setTimeout hack for this exact problem or reached for lodash without fully trusting what its defaults do.

Why debounce and throttle exist
The mental model: a bouncer, not a filter
Stage 1: debounce from scratch
Stage 2: throttle from scratch
Stage 3: leading and trailing edges
Stage 4: cancel, flush, and cleanup
Stage 5: using them in React
Edge cases and gotchas
Best practices
FAQ
Cheat sheet
Key takeaways

Why debounce and throttle exist

Here's the naive version of a live search box — the one almost everyone writes first:

// the wrong way — fires a request on every single keystroke
searchInput.addEventListener("input", (event) => {
  fetchResults(event.target.value); // one HTTP request per keystroke
});

Type a six-letter word at a normal pace and this fires six requests in well under a second, five of which are already obsolete by the time their responses arrive. Worse, network responses don't always resolve in the order they were sent — a slow response for jav can arrive after the fast response for javascript, and now the screen is showing stale results for a query the user already replaced. The bug isn't visible in a quick manual test because your laptop and the API are both fast; it shows up for a real user on a real network, and by then it looks like "search is flaky" rather than "search fires way too often."

The same shape of problem hits scroll and resize handlers, just with a different failure mode. A scroll event can fire dozens of times per second. If the handler does anything nontrivial — reading getBoundingClientRect(), updating layout, running a chunk of business logic — the page starts dropping frames and scrolling turns jerky, even though nothing is technically "broken."

Both problems come from the same root cause: the event source fires far more often than the response actually needs to run. Debounce and throttle are two different answers to "how often is often enough," and they are not interchangeable.

The mental model: a bouncer, not a filter

The mental model: neither function filters events — every event still reaches your wrapper and every event still runs a check. What changes is how often the check lets the real work through, and the two functions use opposite strategies for deciding that.

Debounce says "wait for quiet." Every call resets a timer. The wrapped function only runs once the calls actually stop for the configured delay. Think of an elevator door: every time someone walks up, the door resets its close timer. It only closes once nobody has approached it for a few seconds.
Throttle says "at most once per interval." It doesn't care whether calls are still coming in — it just refuses to let the wrapped function run again until a fixed amount of time has passed since the last time it ran. Think of a metronome, or a bouncer who lets one person through the door every two seconds regardless of how long the line is.

That single distinction — "wait for silence" versus "space it out at a fixed rate" — explains almost every behavior difference in the rest of this guide. Debounce is right when you only care about the final state (the finished search query). Throttle is right when you need regular updates during continuous activity (a scroll position that should keep updating while the user scrolls).

Stage 1: debounce from scratch

The smallest correct debounce is short — a closure holding one timer ID:

function debounce(fn, delayMs) {
  let timeoutId; // lives across calls thanks to the closure
  return function debounced(...args) {
    clearTimeout(timeoutId); // cancel whatever was pending
    timeoutId = setTimeout(() => fn.apply(this, args), delayMs);
  };
}

const debouncedSearch = debounce((query) => fetchResults(query), 300);
searchInput.addEventListener("input", (e) => debouncedSearch(e.target.value));

Key concept: every call to debounced cancels the previous pending timer and starts a new one. fn only ever actually runs if 300ms pass with no new call in between — which is exactly "wait for quiet," implemented as literally as possible.

Type "js" quickly and debounced runs twice (once per keystroke) but fn runs zero times until you stop — then it runs exactly once, 300ms after your last keystroke, with the final value of query. That's the whole mechanism. Everything else in this guide is a variation on this six-line function.

Stage 2: throttle from scratch

Throttle needs to track when it last ran, not whether a timer is pending:

function throttle(fn, intervalMs) {
  let lastRun = 0; // timestamp of the last time fn actually executed
  return function throttled(...args) {
    const now = Date.now();
    if (now - lastRun >= intervalMs) {
      lastRun = now;
      fn.apply(this, args);
    }
  };
}

const throttledOnScroll = throttle(() => updateScrollProgress(), 100);
window.addEventListener("scroll", throttledOnScroll);

Key concept: this implementation runs fn immediately on the very first call (because now - lastRun starts effectively infinite), then ignores every call until intervalMs has elapsed, at which point the next call through gets to run. Calls that arrive during the "cooldown" are dropped entirely — not queued, not delayed, just discarded.

That last detail matters: with this specific implementation, if the burst of calls stops during a cooldown window, the very last call in the burst is simply lost — fn doesn't get one final run with the latest arguments. Stage 3 fixes that.

Stage 3: leading and trailing edges

"Leading edge" means running on the first call in a burst; "trailing edge" means running once more after the burst ends, with the latest arguments. The debounce in Stage 1 is trailing-only. The throttle in Stage 2 is leading-only. A production-grade version usually supports both, because dropping the trailing call (throttle) or delaying every call including the first one (debounce) is sometimes the wrong tradeoff:

function throttle(fn, intervalMs, { leading = true, trailing = true } = {}) {
  let lastRun = 0;
  let timeoutId = null;
  let lastArgs = null;

  return function throttled(...args) {
    const now = Date.now();
    const remaining = intervalMs - (now - lastRun);
    lastArgs = args;

    if (remaining <= 0) {
      if (leading || lastRun !== 0) {
        lastRun = now;
        fn.apply(this, args);
      }
    } else if (trailing && !timeoutId) {
      timeoutId = setTimeout(() => {
        timeoutId = null;
        lastRun = Date.now();
        fn.apply(this, lastArgs);
      }, remaining);
    }
  };
}

Key concept: leading controls whether the very first call in a burst runs immediately; trailing controls whether one extra call fires after the burst goes quiet, using whatever arguments arrived last. lodash's _.throttle defaults to { leading: true, trailing: true }, and its _.debounce defaults to { leading: false, trailing: true } — which is exactly why debounce "feels like" it only fires at the end, while throttle "feels like" it fires immediately and then periodically.

Stage 4: cancel, flush, and cleanup

A debounce or throttle you can't cancel is a liability the moment its owner disappears — a component unmounts, a modal closes, a request is superseded. Attach the controls directly to the returned function:

function debounce(fn, delayMs) {
  let timeoutId;
  function debounced(...args) {
    clearTimeout(timeoutId);
    timeoutId = setTimeout(() => fn.apply(this, args), delayMs);
  }
  debounced.cancel = () => clearTimeout(timeoutId); // drop the pending call
  return debounced;
}

const debouncedSave = debounce(saveDraft, 500);
debouncedSave("draft text");
debouncedSave.cancel(); // "draft text" will never be saved

flush() is the mirror image: run the pending call right now instead of waiting or dropping it — useful when the user explicitly submits a form while a debounced autosave is still pending, so the two writes don't race.

Stage 5: using them in React

The trap in React isn't the debounce function itself — it's where you create it. Creating a new debounced function on every render breaks the whole mechanism, because each render's closure has no memory of the previous render's timer:

// the wrong way — a brand-new debounce (and a brand-new timer) every render
function SearchBox() {
  const [query, setQuery] = useState("");
  const debouncedSearch = debounce((q) => fetchResults(q), 300); // recreated every render

  return (
    <input
      value={query}
      onChange={(e) => {
        setQuery(e.target.value);
        debouncedSearch(e.target.value); // this instance's timer never gets to fire before a new one replaces it
      }}
    />
  );
}

Create the debounced function once, with useMemo or useRef, and cancel it on unmount:

function SearchBox() {
  const [query, setQuery] = useState("");
  const debouncedSearch = useMemo(() => debounce((q) => fetchResults(q), 300), []);

  useEffect(() => {
    return () => debouncedSearch.cancel(); // no fetch after this component is gone
  }, [debouncedSearch]);

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

Key concept: the debounced function must outlive individual renders (created once, stored in a ref or memoized with an empty dependency array) and must be explicitly cancelled in a cleanup function, or its pending timer will call fetchResults on state that no longer exists.

Edge cases and gotchas

Stale closures. If fn inside a debounce/throttle closes over a variable that changes between calls (a piece of state, a prop), the call that eventually fires can use an outdated value. useCallback/useRef patterns exist specifically to solve this in React; in vanilla JS, pass the current value as an argument rather than relying on the closure.
this binding. The hand-written implementations above use fn.apply(this, args) so a debounced/throttled method still sees the right this. If you strip that out, calling debounce(obj.method, 300)() silently breaks this inside method.
Debouncing an async function doesn't cancel in-flight work. Debounce delays calling the function; it does nothing about a fetch that's already in progress from a previous call. Pair debounce with an AbortController if a slow, superseded request could still resolve and overwrite a newer one.
Race conditions between the trailing call and unmount. A debounce's setTimeout keeps a reference to fn alive even after the component that created it is gone. Without cancel() on cleanup, the trailing call still fires and can throw ("cannot update state on an unmounted component") or write to a resource that no longer applies.
Throttle intervals and animation. A scroll or mousemove throttle set to a fixed millisecond interval can visibly stutter, because it's not synchronized with the browser's paint cycle. For anything visual, prefer requestAnimationFrame-based throttling: run at most once per frame instead of once per N milliseconds.
Testing. Both patterns depend on real time passing, which makes tests flaky if you sleep. Use fake timers (jest.useFakeTimers() / vi.useFakeTimers()) and advance them explicitly (jest.advanceTimersByTime(300)) instead of waiting on the wall clock.
Debounce delay versus perceived responsiveness. A 300ms debounce feels instant to most users; anything above ~500ms on a search-as-you-type field starts to feel sluggish, because the user has already mentally "sent" the query.

Best practices (when (not) to use them)

Reach for debounce when you only care about the value once activity settles: search-as-you-type, autosave, form validation that shouldn't run on every keystroke, resize-triggered layout recalculation where only the final size matters.

Reach for throttle when you need periodic updates during continuous activity, not just at the end: scroll-position tracking, a progress indicator following mousemove, rate-limiting how often a "user is typing" indicator pings a server, infinite-scroll trigger checks.

Avoid both when the action needs to feel instantaneous every single time — a button click, an "add to cart," a keyboard shortcut. Delaying or dropping those erodes trust in the UI even if it's technically more "efficient." If a click handler is slow, fix the handler; don't debounce the click.

Don't stack them by accident. Wrapping an already-throttled handler in another library's debounce (or vice versa) is a common cause of "my scroll handler feels randomly laggy" bugs — pick one strategy per event source and be deliberate about the delay.

FAQ

What's the actual difference between debounce and throttle?

Debounce waits for a pause in activity and then runs once; throttle runs at a fixed maximum rate regardless of whether activity is still ongoing. Debounce answers "what's the final state?"; throttle answers "give me periodic updates while this keeps happening."

Does lodash's `_.debounce` behave differently from a hand-rolled one?

Functionally, a correct hand-rolled trailing-edge debounce matches _.debounce's default behavior (leading: false, trailing: true). lodash additionally ships cancel(), flush(), and a maxWait option (a ceiling on how long calls can be delayed even under continuous activity) — genuinely useful extras, not a different core algorithm.

Can I debounce an async function?

Yes, but debounce only controls when the call happens — it has no knowledge of what the async function does afterward. If an earlier (superseded) call's promise resolves after a later one, you can still get out-of-order results unless you also track "is this the latest call" or cancel the earlier request with an AbortController.

Should I use `requestAnimationFrame` instead of throttle for scroll or resize?

For anything that updates visuals (position, size, opacity), yes — requestAnimationFrame throttling caps the work at once per paint, which is both smoother and never more work than the browser can actually display. Millisecond-based throttling is still the right tool for non-visual rate-limiting, like capping how often you ping an analytics endpoint.

How do I cancel a debounced or throttled call?

Attach a .cancel() method to the returned function (Stage 4) and call it — in setTimeout's case that's a clearTimeout; for lodash, _.debounce and _.throttle both return functions with a built-in .cancel().

Cheat sheet

Task	Code	Notes
Debounce (trailing only)	`debounce(fn, 300)`	Runs once, 300ms after calls stop. Best for search/autosave.
Throttle (leading + trailing)	`throttle(fn, 100, { leading: true, trailing: true })`	Runs immediately, then at most every 100ms, plus once more after the burst ends.
Cancel a pending call	`debounced.cancel()`	Clears the timer; the delayed call never runs.
Flush a pending call now	`debounced.flush()`	Runs the pending call immediately instead of waiting.
Visual/animation rate-limit	`requestAnimationFrame` loop	Caps work to once per paint; smoother than a fixed-ms throttle for scroll/resize.
React: create once	`useMemo(() => debounce(fn, ms), [])`	Never recreate inside the render body.
React: cleanup	`useEffect(() => () => debounced.cancel(), [])`	Prevents calls firing after unmount.

// the whole pattern, copy-paste ready
function debounce(fn, delayMs) {
  let timeoutId;
  function debounced(...args) {
    clearTimeout(timeoutId);
    timeoutId = setTimeout(() => fn.apply(this, args), delayMs);
  }
  debounced.cancel = () => clearTimeout(timeoutId);
  return debounced;
}

function throttle(fn, intervalMs, { leading = true, trailing = true } = {}) {
  let lastRun = 0;
  let timeoutId = null;
  let lastArgs = null;

  function throttled(...args) {
    const now = Date.now();
    const remaining = intervalMs - (now - lastRun);
    lastArgs = args;

    if (remaining <= 0) {
      if (leading || lastRun !== 0) {
        lastRun = now;
        fn.apply(this, args);
      }
    } else if (trailing && !timeoutId) {
      timeoutId = setTimeout(() => {
        timeoutId = null;
        lastRun = Date.now();
        fn.apply(this, lastArgs);
      }, remaining);
    }
  }
  throttled.cancel = () => {
    clearTimeout(timeoutId);
    timeoutId = null;
  };
  return throttled;
}

🎮 Try it yourself

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

Key takeaways

Debounce waits for quiet and runs once at the end; throttle runs on a fixed schedule no matter how long the activity continues.
Every event still reaches the wrapper — what changes is how often the real work behind it is allowed to run.
Use debounce for "what's the final value" (search, autosave); use throttle (or requestAnimationFrame) for "keep me updated while this continues" (scroll, resize, drag).
Both need cancel() wired into cleanup — an uncancelled debounce or throttle is a call waiting to fire on a component that no longer exists.
Create the wrapped function once, not on every render.

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

That search box from the opening paragraph needs exactly one line changed — wrap the handler in debounce(fetchResults, 300) — and the ten wasted requests become one, fired the moment the user actually stops typing. Which of your own event handlers is still firing ten times more than it needs to?

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected:

⭐ GitHub — follow me and star the projects: github.com/parsajiravand
💬 Discord — join the frontend best-practices community: discord.gg/d9KRhuAwQ
📸 Instagram — frontend best practices, daily: @bestpractice___

You Don't Need a WebSocket for That Live Feed

Parsa Jiravand — Mon, 31 Aug 2026 13:11:42 +0000

You need a live notification badge. The count in the corner should tick up the moment something happens on the server — no refresh, no polling every three seconds hoping you didn't miss anything. So you do what everyone does: npm install socket.io, wire up a client, and ship it.

Then someone's wifi hiccups for two seconds. The socket drops. Nothing reconnects, because you didn't write that part yet. Now you're writing it — a reconnecting flag, a backoff timer that doubles each attempt, a cap so it doesn't retry forever, a check for whether the tab is even in the foreground. Forty-something lines later you have a hand-rolled connection manager sitting in front of a feature that only ever sent data in one direction: server to browser.

There's a browser API that already does the part you just spent an afternoon on. It's been sitting in every evergreen browser for over a decade, and it's not the one you reached for.

The wrong way, in more detail than you wanted

Here's roughly what that WebSocket reconnect logic looks like once it's "done":

let socket;
let retryDelay = 1000;

function connect() {
  socket = new WebSocket('wss://api.example.com/notifications');

  socket.onopen = () => { retryDelay = 1000; };

  socket.onmessage = (event) => {
    updateBadge(JSON.parse(event.data));
  };

  socket.onclose = () => {
    setTimeout(connect, retryDelay);
    retryDelay = Math.min(retryDelay * 2, 30000);
  };

  socket.onerror = () => socket.close();
}

connect();

It works. It's also code you didn't want to own: a manual backoff schedule, a retryDelay you have to remember to reset on success, and a close/error interaction that's easy to get subtly wrong (fire both handlers and you'll double-schedule a reconnect). And you still haven't handled resuming — if the connection drops mid-stream, you have no idea what the server sent while you were gone. You just start fresh and hope you didn't miss the one notification that mattered.

None of that is a WebSocket problem, exactly. It's what you get for using a bidirectional, binary-capable protocol for a feature that only ever pushes text from server to client.

What you're actually asking for

Strip the feature down to what it needs: the server pushes updates, the browser listens, and if the connection drops, it should pick back up without you writing a state machine. That's Server-Sent Events — an HTTP response that never ends, plus a browser-side API called EventSource that reads it.

The client side is almost embarrassingly small:

const stream = new EventSource('/api/notifications');

stream.onmessage = (event) => {
  updateBadge(JSON.parse(event.data));
};

stream.onerror = () => {
  // the browser is already retrying — this just tells you it happened
  console.warn('connection dropped, reconnecting…');
};

That's it. No retryDelay, no setTimeout, no connect() function to call again. If the connection drops — the wifi hiccup, a proxy timeout, the server restarting — the browser reconnects on its own. You didn't write that part because it isn't yours to write.

The part that replaces your backoff timer

The server side is a plain HTTP response with one specific content type and a text format the browser knows how to parse:

app.get('/api/notifications', (req, res) => {
  res.set({
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    Connection: 'keep-alive',
  });

  const send = (data) => res.write(`data: ${JSON.stringify(data)}\n\n`);

  const unsubscribe = notifications.subscribe(send);
  req.on('close', unsubscribe);
});

Each message is a data: line followed by a blank line — that blank line is what tells the browser "this event is complete, hand it to onmessage." Send that content type and keep the connection open, and you've built the entire server half of what socket.io was doing for you, minus the parts you didn't need.

The reconnection is where it earns the comparison to your backoff timer. When the browser reconnects after a drop, it's not just retrying blindly — it sends a Last-Event-ID header carrying the ID of the last event it successfully received, so the server can pick the stream back up instead of replaying everything or losing the gap:

const send = (data, id) => {
  res.write(`id: ${id}\n`);
  res.write(`data: ${JSON.stringify(data)}\n\n`);
};

app.get('/api/notifications', (req, res) => {
  res.set({ 'Content-Type': 'text/event-stream' });
  const lastId = req.headers['last-event-id'];
  const missed = notifications.since(lastId); // your own backlog logic
  missed.forEach((n) => send(n.payload, n.id));
  const unsubscribe = notifications.subscribe(send);
  req.on('close', unsubscribe);
});

You still have to write notifications.since() — SSE gives you the mechanism for catching up, not the backlog itself. But that's a data-layer problem you'd have had with a WebSocket too, except there you'd also be reimplementing the ID and the reconnect trigger by hand.

Want to change how long the browser waits before its first reconnect attempt? The server can set that too, with a retry: line — the value's in milliseconds:

retry: 5000
data: {"count": 3}

Skip it and the browser falls back to its own default of a few seconds, which is fine for most dashboards and badges.

🎮 Try it yourself

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

Where this stops being the right tool

SSE isn't a WebSocket replacement — it's the right tool for a narrower job, and it's worth being honest about the edges before you reach for it everywhere:

It's one-way. The stream only carries server → client. If the browser needs to send something back — a chat message, a cursor position, a game input — that's a normal fetch call on the side, not a message over the same connection. The moment the client needs to talk back in real time, you're back to WebSockets.
It's text only. Every event is UTF-8. Binary data — audio chunks, protobuf, anything you'd otherwise send as a Blob or ArrayBuffer — has to be base64-encoded first, which is exactly the kind of tax that makes WebSockets or WebRTC the better call for that payload.
HTTP/1.1 caps you at six connections per browser, per origin. Because each EventSource holds a request open indefinitely, a user with several tabs open to your app can exhaust that limit and starve other requests on the same domain. Serve your app over HTTP/2 (most CDNs and reverse proxies do this by default now) and the cap disappears, because HTTP/2 multiplexes many streams over one connection — but it's worth checking, not assuming.

If your feature needs the client to send data in the same real-time loop, or needs binary frames, that's your WebSocket. If it's a one-way trickle of small text updates — a badge, a progress indicator, a live dashboard number, a "someone else is editing this doc" banner — you were reaching for the heavier tool.

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

Next time a feature description is "push updates from the server, nothing coming back," open your network tab before you open your package.json. Check whether EventSource covers it first — you might delete a reconnect handler instead of writing one.

Have you shipped a WebSocket for something that turned out to be one-way the whole time? Tell me what it was — I'd bet it's more common than the socket.io download numbers suggest.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected:

⭐ GitHub — follow me and star the projects: github.com/parsajiravand
💬 Discord — join the frontend best-practices community: discord.gg/d9KRhuAwQ
📸 Instagram — frontend best practices, daily: @bestpractice___

DEV Community: Parsa Jiravand

Your Recipe App Is Hiding a Silent Video

The problem it's solving

Where it falls apart

The API that says what it means

🎮 Try it yourself

The part the happy path hides

Ship it without breaking the browsers that don't have it

The one-pixel video, decoded

🧠 Test yourself

React Compiler 1.0: What useMemo You Can Delete

What you'll learn

Who this is for

Table of contents

The problem: manual memoization doesn't scale

The mental model: what memoization actually buys you

Stage 1: the re-render, without memoization

🎮 Try it yourself

Stage 2: the manual fix, and its subtle crack

Stage 3: the same code, compiled

Stage 4: turning it on

Edge cases and gotchas

Best practices

FAQ

Does React Compiler replace useEffect?

Do I still need React.memo, useMemo, or useCallback with the compiler installed?

Is it safe to delete all my existing useMemo/useCallback calls right now?

Does React Compiler work with React 18 or older?

What happens if my component breaks the Rules of React?

How do I stop the compiler from touching one specific component?

Cheat sheet

🧠 Test yourself

Key takeaways

Your Timer Doesn't Know You Tabbed Away

The fix that feels obvious

The question you meant to ask

🎮 Try it yourself

Wiring it up properly

🧠 Test yourself

Focus and visibility are different questions — use the one you mean

NestJS Dependency Injection Explained (with Cheat Sheet)

What you'll learn

Who this is for

Table of contents

The problem: a singleton that isn't

The mental model: registrations, not classes

🎮 Try it yourself

Stage 1: the simplest provider

Stage 2: sharing one instance across modules

Stage 3: custom providers — when a class isn't enough

Stage 4: provider scopes — DEFAULT, REQUEST, TRANSIENT

Stage 5: scope bubbling

Edge cases and gotchas

Best practices

🧠 Test yourself

FAQ

Is a NestJS provider actually a singleton?

How do I get two different instances of the same service on purpose?

Does exporting a provider create a new instance?

Why does @Inject() show up on some constructor parameters and not others?

Does REQUEST scope work the same way in WebSocket gateways and microservices?

Cheat sheet

Key takeaways

Stop Regex-Parsing document.cookie. Use CookieStore

What everyone reaches for instead

The API that actually does this: cookieStore

🎮 Try it yourself

The default that's stricter than you're used to

Two things worth knowing before you reach for it

The takeaway

🧠 Test yourself

The await That Silently Breaks navigator.clipboard.writeText()

The fixes that don't touch it

The real rule: the API only trusts the instant of the click

🎮 Try it yourself

The fix: give the API the gesture immediately, the data later

Two details worth knowing before you ship this

The one thing worth remembering

🧠 Test yourself

You're not quiet in meetings, you're editing

Why does `@Inject()` show up on some constructor parameters and not others?

The API that actually does this: `cookieStore`

Stage 2: caching data with `use cache`

Stage 3: caching a component, and reading `cacheLife`

Stage 5: invalidating on demand with `cacheTag`

Do I have to enable `cacheComponents` to use Next.js 16?

Does Cache Components replace `revalidatePath`?

Does `use cache` persist across deployments?

What happens if I forget `cacheLife` on a `use cache` function?

How `pushState` routing actually works

What you get that `pushState` never gave you

Does lodash's `_.debounce` behave differently from a hand-rolled one?

Should I use `requestAnimationFrame` instead of throttle for scroll or resize?