DEV Community: Parsa J

Stop Shipping Search Boxes With a Race Condition

Parsa J — Sat, 07 Nov 2026 06:21:08 +0000

Type "react" into a search box, watch it fetch results, then quickly backspace and type "vue" instead. For half a second, the dropdown shows react results under the word vue. Then it corrects itself, or it doesn't, and either way nobody files a bug report because by the time you'd screenshot it, it's gone.

This happened at a filter UI I worked on — product search, nothing exotic, one fetch() call per keystroke. QA flagged it as "occasionally shows stale results, can't reproduce." That phrase should make you suspicious immediately. "Can't reproduce" usually means "reproduces under conditions I'm not controlling for" — and the condition here was network speed, which nobody controls on purpose.

The fix that made it rarer, not gone

The instinct, reasonably, was to stop firing so many requests:

let timer;
searchInput.addEventListener("input", (e) => {
  clearTimeout(timer);
  timer = setTimeout(() => runSearch(e.target.value), 250);
});

async function runSearch(query) {
  const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`);
  const data = await res.json();
  renderResults(data);
}

Debounce the input, wait 250ms of silence before firing. Fewer requests, fewer chances to collide — the bug got rarer. It did not go away. On a slow connection, or with a server that happens to answer a short query faster than a long one, two debounced requests can still be in flight at once, and they can still finish in the wrong order.

Before you keep reading — what do you think "wrong order" actually means here? It's not that the requests go out of order. It's that they come back out of order, and nothing in the code above checks which one it's looking at before painting it on screen.

The response you render isn't the one you think it is

Here's the part that doesn't show up in a quick read of the code: fetch() makes no promise about finish order. You can send request A, then request B a moment later, and B's response can arrive first — a shorter query, a warmer cache entry, a server that happens to be less loaded for that specific request. Nothing is broken. This is just what concurrent network calls do.

renderResults(data) in the snippet above has no idea which query the data it just received belongs to. It just paints whatever shows up last. If A was "react" and B was "vue", and A's response happens to land after B's, the box ends up showing react results while the input says vue. The bug isn't in your fetch call. It's in the fact that you're treating "the last response that arrived" as if it were "the response to my last request" — and those are only the same thing when nothing is racing.

That's the whole bug, named precisely: it's a race condition — two async operations whose outcome depends on which one happens to finish first, and "happens to" is exactly the word that should worry you. It's not about when things run on the main thread. It's about the gap between starting an operation and acting on its result, and anything else that can also act in that gap.

The fix: stop trusting arrival order, track identity instead

You can't force responses to come back in order — that's a property of the network, not your code. What you can do is make sure that when a response arrives, you check whether it's still the one you care about before you act on it.

The smallest version of that is a counter:

let latestRequestId = 0;

async function runSearch(query) {
  const requestId = ++latestRequestId;

  const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`);
  const data = await res.json();

  if (requestId !== latestRequestId) {
    return; // a newer search started while this one was in flight — drop it
  }

  renderResults(data);
}

Every call to runSearch claims the next number and remembers it. When its response finally arrives — however late, however out of order — it checks whether it's still the most recent request anyone asked for. If a newer one started in the meantime, this one's result is thrown away, silently, no matter how long it took to get here. The one request that's still "latest" when its answer arrives is the only one allowed to touch the DOM.

Three lines. No library, no state management rewrite. The requests still race each other exactly as before — you've just stopped letting the loser win.

If you'd rather cancel the stale request outright instead of just ignoring its answer, AbortController does that — controller.abort() on the previous request before firing a new one, and a caught AbortError instead of the manual counter check. That trims a network call that would otherwise complete for nothing, which is worth it on anything heavier than a search box. The counter guard above is the version to reach for when you don't control the request layer, or just want the smallest possible fix.

🎮 Try it yourself

▶️ Open the interactive playground →

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

It's not just search boxes

Once you see this shape, you start noticing it everywhere two async calls can overlap and only one should win:

Tabs in a dashboard — click "Revenue," then quickly click "Users." If Revenue's data is bigger and arrives after Users', the Users tab briefly shows revenue numbers.
Infinite scroll with filters — change a filter mid-scroll, and an in-flight page request for the old filter lands after the new one does.
Autosave — type, pause, type again, pause. Two save requests, and if the first one is slow, it can overwrite the second one's result on the server.
Optimistic UI rollback — a retry fired after a timeout can resolve after the original request you thought had failed, and now you've "rolled back" a success.

Every one of these has the same fix: attach an identity to the thing you're waiting for, and check it's still current before you act on the answer. React Query and SWR build this in for you automatically — stale responses are dropped before they ever reach your UI, which is a large part of why "just use a data-fetching library" is good advice, not laziness. Redux Toolkit's createAsyncThunk doesn't drop them for you, but it hands you the exact piece the guard above needs: every dispatched thunk carries a unique meta.requestId, so instead of inventing your own counter you compare that id in your reducer. But knowing the three-line version means you're never stuck when you're not using one of those, which is most code that isn't a component's data layer.

Guard the identity, not the order

The lesson generalizes past fetch: whenever you start an async operation and plan to act on its result later, something else can start in the meantime and finish first. You can't make the network, the event loop, or another developer's code behave in request order for you. You can make sure that when a result shows up, you check whether it's still the one you're waiting for before you let it touch anything a user can see.

Go find the oldest fetch() or setTimeout callback in your codebase that fires more than once per user action — a search box, a save button, a polling loop. Does anything check that the response it just got is still the one it wants? If the honest answer is no, you've found a race condition that just hasn't been unlucky yet.

🧠 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___

You're Blocking Scroll by Default. `passive: true` Fixes It.

Parsa J — Fri, 06 Nov 2026 06:10:54 +0000

A teammate scrolled the product list on their phone and said it felt "sticky" — not broken, just a little behind, like the page was thinking about it before it moved. On a laptop trackpad it was perfectly smooth. Same code, same list, same 12-line scroll handler that did almost nothing: check scrollY, toggle a "back to top" button.

Twelve lines. Nothing in it that should cost more than a millisecond. And yet, on a phone, every scroll felt like it had a half-beat of drag.

The fix that didn't fix it

The obvious read is "the handler is too slow," so that's where the first hour went:

list.addEventListener("scroll", () => {
  backToTop.hidden = list.scrollTop < 400;
});

Wait — not even scroll. The actual listener was on touchmove, added so the button could react mid-gesture instead of waiting for the scroll to settle:

list.addEventListener("touchmove", () => {
  backToTop.hidden = list.scrollTop < 400;
});

That one line is the whole bug, and nothing in it looks dangerous. We debounced it. We memoized the scroll position. We moved the class toggle behind requestAnimationFrame. Chrome DevTools' performance panel kept showing the same thing after every change: a yellow "Rendering" block sitting before the scroll could start, not after the handler ran.

Before you keep reading — what do you think the browser was actually waiting for?

It wasn't waiting for the handler to be fast. It was waiting to find out whether the handler would call preventDefault().

Why a `touchmove` listener can freeze a scroll that never gets cancelled

touchmove, touchstart, and wheel are special. Any listener for one of them is allowed to call event.preventDefault() and cancel the browser's default action — in this case, cancel the scroll itself, mid-gesture. A custom image-zoom gesture, a swipe-to-dismiss card, a "no, don't scroll past this point" lock — all of those work by listening to one of these events and vetoing the browser's plan.

The browser doesn't know in advance that your handler isn't one of those. So by default it plays it safe: run the handler first, check event.defaultPrevented, and only then move the page. Your handler reads scrollY and sets .hidden — completely harmless — but the browser can't see that from the outside. It has to ask.

That ask is synchronous, and it happens on the main thread. If the main thread is busy with literally anything else at that instant — a re-render, a timer, a layout recalculation — the scroll waits behind it. Debouncing the handler doesn't help, because the delay isn't the handler's duration. It's the fact that scrolling is gated on the handler returning at all, every single time it fires.

This is exactly what Lighthouse is flagging when it tells you a page "does not use passive listeners to improve scrolling performance." It isn't measuring your code's speed. It's measuring whether you've told the browser it's allowed to stop asking.

🎮 Try it yourself

▶️ Open the interactive playground →

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

The one-line fix

addEventListener takes a third argument beyond the usual boolean-for-capture — an options object with a passive flag:

list.addEventListener("touchmove", () => {
  backToTop.hidden = list.scrollTop < 400;
}, { passive: true });

{ passive: true } is a promise: this listener will never call preventDefault(). The browser takes you at your word, stops waiting, and starts scrolling the instant the gesture begins — on the compositor thread, independent of whatever your handler is doing. The handler still runs, still takes however long it takes, but scrolling no longer holds its breath for the answer.

Break that promise and call preventDefault() inside a passive listener anyway, and nothing happens — the call is silently ignored. Chrome and Firefox log a console warning telling you so; Safari doesn't, so don't count on the console to catch the mistake for you. There's no partial credit. A listener is either allowed to cancel the gesture, or it isn't, and passive is you choosing which.

Try scrolling the list below with the toggle off, then on — same handler, same cost, very different feel.

"Isn't this already the default?"

Sort of, and that's the trap. A few browsers quietly mark some touch listeners passive on their own — but only in specific cases (certain root-level targets, specific event types), and the exact cases differ by engine and have changed over time as each one shipped its own optimization. Relying on an undocumented default that varies by browser and by which element you attached to is not a strategy. It's a bet.

The one-line fix works everywhere, on every engine, whether or not that engine happens to be feeling generous today:

list.addEventListener("touchmove", handler, { passive: true });
list.addEventListener("wheel", handler, { passive: true });

Add it to every touchstart, touchmove, or wheel listener where you genuinely never call preventDefault() — scroll-position trackers, infinite-scroll triggers, analytics pings, "show the nav on scroll up" toggles, if you've wired them to one of those three events. That's most of them. (A plain scroll listener doesn't need this at all — scroll events are never cancelable, so the browser was never waiting on them in the first place.) The only time you can't use { passive: true } is when the listener sometimes needs to cancel the gesture — a custom swipe handler, a drag-to-reorder list, a pinch-zoom lock. In that case, leaving it non-passive is correct, not an oversight — you're keeping the veto because you actually use it.

The list, scrolling again

Back-to-top button, 12 lines, one options object added. The teammate who first noticed the stutter scrolled the same list on the same phone and didn't say anything — which, for a performance fix, is exactly the review you want. Nobody writes a bug report about something that just works.

Go check one scroll handler in your own codebase right now — does it call preventDefault() anywhere? If the honest answer is no, it's missing one argument. What's the oldest scroll listener in your code that's never had { passive: true } added — and do you know whether it blocks anything?

🧠 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.

📚 Read next

🚀 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 12.2: Why validationError.target Is Now undefined

Parsa J — Fri, 06 Nov 2026 06:10:24 +0000

A NestJS app upgrades from @nestjs/core 12.1 to 12.2 — npm i @nestjs/core@latest @nestjs/common@latest, nothing else touched. The test suite stays green. In production, an audit log that has recorded every failed signup for months — the field that failed, the message, and the full payload the user actually submitted — starts writing submittedPayload: undefined on every single entry. No exception, no crash, no warning in the logs. The validation itself still works exactly as before: bad input still gets rejected with a 400. Only the forensic trail disappeared.

This is written against @nestjs/core 12.2.0 (verified 2026-10-20 via npm view @nestjs/core dist-tags and the official v12.2.0 release notes; 12.0.0 shipped 2026-08-27, and the 11.x line remains on the legacy npm tag at 11.2.7). The change described here — validationError.target defaulting to false — is listed by name in that release's "new defaults and behaviour changes" section, not inferred from a diff. It applies to the class-validator-based ValidationPipe only; it does not touch the newer StandardSchemaValidationPipe covered in an earlier episode of this series.

What you'll learn

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

Explain exactly what target, value, and property each mean on a class-validator ValidationError, and which of them NestJS's own built-in exceptionFactory actually uses
State precisely why @nestjs/core 12.2 changed validationError.target's default to false, in the maintainers' own words
Fix a custom exceptionFactory that silently breaks on the upgrade, without just disabling the new default
Restore the pre-12.2 behavior deliberately, globally or per pipe, when you genuinely need it
Place this change correctly on the request lifecycle's pipes stage, and rule out the two other places it could be confused for a bug

Who this is for

You've registered a ValidationPipe — global or scoped — against class-validator DTOs at least once, and ideally you've written or read a custom exceptionFactory. If you haven't read this series' NestJS request lifecycle episode, it maps exactly where a pipe runs relative to guards, interceptors, and filters — useful background, but this article stands on its own.

The problem: an exceptionFactory that used to work
The mental model: target, value, and property are three different things
Stage 1: why 12.2 changed the default
Stage 2: fixing the broken exceptionFactory
Stage 3: restoring the old behavior on purpose
Stage 4: the quieter 12.2 changes riding along
Edge cases and gotchas
Best practices
FAQ
Cheat sheet
Key takeaways

The problem: an exceptionFactory that used to work

Here's the pipe registration behind the audit log in the intro, unchanged across the upgrade:

// main.ts
app.useGlobalPipes(
  new ValidationPipe({
    exceptionFactory: (errors) => {
      const first = errors[0];
      auditLog.record({
        field: first.property,
        message: Object.values(first.constraints ?? {})[0],
        // this line is what broke — quietly
        submittedPayload: first.target,
      });
      return new BadRequestException(errors);
    },
  }),
);

Before 12.2, first.target was the whole object class-validator had just validated — the full DTO instance built from the request body, every field included, whether it passed or failed. That made it an easy, if slightly lazy, way to log "here's exactly what the user sent" next to the one field that failed. After 12.2, with nothing else in the application touched, first.target is undefined. submittedPayload: undefined is syntactically valid, so nothing throws — the audit log entry is just worse than it was.

The mental model: target, value, and property are three different things

The mental model: a class-validator ValidationError is a small record for one failing property, and it can carry up to four separate pieces of information about that failure — and only one of them changed in 12.2:

property — the name of the field that failed, e.g. "email". Always present. Unaffected by this change.
constraints — a map of rule name to human-readable message, e.g. { isEmail: "email must be an email" }. Always present. Unaffected.
value — the actual value that was submitted for that one field, e.g. "not-an-email". This is scoped to the failing property alone. Unaffected by the 12.2 change.
target — not the field's value, but the entire object being validated, with every property, whether it passed or failed. This is the one @nestjs/core 12.2 now suppresses by default.

That distinction is the whole article: value tells you what was wrong with the one field that failed; target repeats the complete request body on every single error in the array. A DTO with three failing fields used to produce three ValidationError objects, each one carrying a full copy of the same object. NestJS's own source comment on the change states the reasoning plainly: "the target of an error is the whole object it was found in, so an exception factory that sends the errors would repeat that object." Repeating it isn't just noisy — it's also how a request body with a password field, a token, or any other sensitive value ends up duplicated into every validation error a naive exceptionFactory forwards to a client or a log.

Stage 1: why 12.2 changed the default

Before @nestjs/core 12.2, ValidationPipe didn't configure validationError for you at all — it passed your validatorOptions straight through to class-validator's validate(), and class-validator's own long-standing default includes target. Since 12.2, ValidationPipe.transform() builds that option itself, and your own setting — if you have one — wins:

// @nestjs/common's ValidationPipe, from 12.2.0 onward (simplified)
const errors = await validate(object, {
  ...this.validatorOptions,
  validationError: {
    target: false, // the new default
    ...this.validatorOptions.validationError, // your setting, if any, overrides it
  },
});

Key concept: this is a default you can always override, not a removed feature. If you never touch validationError, you now get target: false. If you explicitly configure validationError: { target: true } on your ValidationPipe, that object sits on top of the spread above and wins, on every version from 12.2 onward.

Stage 2: fixing the broken exceptionFactory

The honest fix usually isn't restoring target — it's noticing that target was the wrong tool for the job. The audit log wanted "what did the user submit," and that's exactly what value already gives you, scoped to the field that actually failed, with no risk of dragging unrelated fields (passwords, tokens) along for the ride:

app.useGlobalPipes(
  new ValidationPipe({
    exceptionFactory: (errors) => {
      const first = errors[0];
      auditLog.record({
        field: first.property,
        message: Object.values(first.constraints ?? {})[0],
        submittedValue: first.value, // scoped to this field — works on every 12.x
      });
      return new BadRequestException(errors);
    },
  }),
);

Key concept: value was never touched by the 12.2 change, on any version. If your exceptionFactory only needs to know what the failing field contained, switching from target to value fixes the bug today and keeps working on whatever the default does next.

If you genuinely need the whole object — reconstructing the full attempted request for a support ticket, say — read on.

Stage 3: restoring the old behavior on purpose

When the full object really is the requirement, say so explicitly instead of relying on an implicit default that already changed once:

app.useGlobalPipes(
  new ValidationPipe({
    validationError: { target: true }, // explicit — survives future default changes
    exceptionFactory: (errors) => {
      const first = errors[0];
      auditLog.record({
        field: first.property,
        message: Object.values(first.constraints ?? {})[0],
        submittedPayload: first.target, // present again, on purpose
      });
      return new BadRequestException(errors);
    },
  }),
);

Key concept: this is scoped to wherever you construct that particular ValidationPipe. A global pipe with validationError: { target: true } restores the old behavior app-wide; a route-scoped @UsePipes(new ValidationPipe({ validationError: { target: true } })) restores it only there, leaving the global pipe on the new, leaner default.

Stage 4: the quieter 12.2 changes riding along

target isn't the only ValidationPipe default the same release changed. Two more are worth knowing before you assume a 400 you're suddenly seeing is a bug in your code:

new ValidationPipe({
  // New in 12.2 — caps how long the combined message string can get.
  // Past this, extra messages are replaced with one "omitted" entry.
  maxErrorMessagesLength: 1_000_000, // this is already the default
});

The other: sending an array or a bare primitive where a validated class is expected now gets a 400 instead of silently passing an unvalidated value through. If a route's DTO is CreateUserDto and the body arrives as [1, 2, 3] or the string "oops", 12.2 rejects it at the pipe instead of letting it reach the handler shaped nothing like the DTO. Both changes ship in the same release and share the same spirit as the target default: stop assuming more than class-validator was actually asked to check.

Edge cases and gotchas

The built-in exceptionFactory was never affected. @nestjs/common's own default error formatter — the one ValidationPipe uses when you don't pass your own — only ever reads property and constraints to build its message array. If you've never written a custom exceptionFactory, this entire change is invisible to you.
Nested DTOs still carry children, not a nested target. A failure on address.zip produces a ValidationError with children: [{ property: 'address', children: [{ property: 'zip', ... }] }]; target suppression applies at every level of that tree the same way.
This is specific to class-validator's ValidationPipe. StandardSchemaValidationPipe (covered in an earlier episode) validates with a Standard Schema library's own ~standard.validate(), which has no target concept at all — nothing here applies to it.
A pipe constructed before you set the option doesn't retroactively pick it up. validationError is read once, in the constructor's resolved options — set it when you call new ValidationPipe({ ... }), not after.
Logging error.target to the console for local debugging is still fine. The change doesn't remove the data from the validation run itself — it only removes it from what reaches exceptionFactory by default. console.log statements inside your own services that build the object from the raw request body are unaffected either way.

Best practices

Default to error.value, not error.target, in any exceptionFactory you write. It's scoped to the one field that failed, was never affected by this change, and can't accidentally leak an unrelated sensitive field.
Never echo the full submitted payload back to the client in an error response, with or without this default — a validation error is exactly the response an attacker can use to fingerprint which fields your DTO expects.
Set validationError: { target: true } explicitly, and only, where you've confirmed you need it — an internal audit log or a support tool, never a response body a client sees.
Audit every custom exceptionFactory in the codebase before upgrading to 12.2, the same way you'd check for any other breaking default: grep -rn "exceptionFactory" src/ and look for .target on the result.
Pin the behavior you rely on, not the default. The target: true default existed for years and still changed once; writing it explicitly means the next default change can't surprise you again.

FAQ

Does this break validation itself, or just error reporting?

Just error reporting. Validation still runs exactly the same way, and the HTTP response code and the fact that invalid requests get rejected are unchanged. Only what a custom exceptionFactory can read off each error changed.

Will my app silently stop validating anything after this upgrade?

No. target being undefined has nothing to do with whether validation ran — it only affects what one specific field on the resulting error object contains.

Does `error.value` ever get suppressed the same way?

No. The 12.2 release notes and the pipe's own source only change the target default; value — the specific field's submitted value — is untouched on every 12.x version.

Is this in the official migration guide, or just the release notes?

It's listed in the v12.2.0 release notes under that release's own "new defaults and behaviour changes," since it's a minor-version default change rather than a major-version breaking change requiring a migration guide entry.

Can I set `validationError.target` per route instead of globally?

Yes — pass the option to a ValidationPipe instance scoped with @UsePipes() on a controller or a single handler, the same way any other ValidationPipe option can be scoped.

Cheat sheet

Task	Code	Notes
Check if your code is affected	`grep -rn "exceptionFactory" src/`	Only custom factories reading `.target` are affected
Fix forward (recommended)	Read `error.value` instead of `error.target`	Scoped to the failing field; unaffected by this change
Restore old behavior, globally	`new ValidationPipe({ validationError: { target: true } })`	Register once, in `main.ts`
Restore old behavior, one route	`@UsePipes(new ValidationPipe({ validationError: { target: true } }))`	Leaves the global pipe on the new default
Confirm the built-in factory is unaffected	Don't pass `exceptionFactory` at all	The default formatter only ever used `property` + `constraints`
`target` vs `value`	`target` = whole submitted object · `value` = one field's value	Only `target` changed its default in 12.2
Other 12.2 `ValidationPipe` defaults	`maxErrorMessagesLength` (new), array/primitive → `400` (new)	Same release, same "stop assuming more than was checked" theme

// main.ts — explicit, upgrade-proof configuration
app.useGlobalPipes(
  new ValidationPipe({
    // Only set this if something genuinely needs the whole submitted object.
    // validationError: { target: true },
    exceptionFactory: (errors) => {
      const first = errors[0];
      return new BadRequestException({
        field: first.property,
        message: Object.values(first.constraints ?? {})[0],
        submittedValue: first.value, // not first.target
      });
    },
  }),
);

Key takeaways

@nestjs/core 12.2 defaults validationError.target to false on ValidationPipe — a deliberate change, documented in the v12.2.0 release notes, not a regression.
target is the entire validated object; value is the one failing field's value. Only target's default changed; value never moves.
NestJS's own built-in exceptionFactory never read target — this only bites a hand-written one, which is exactly why it fails silently instead of at boot.
Fix forward by reading error.value, or restore the old behavior deliberately with validationError: { target: true }, globally or per route.
This lives entirely in the pipes stage of the request lifecycle — guards, interceptors, and filters are untouched by it.

Ending

The bug in the intro was never really about NestJS removing something — it was about a default quietly doing less work on an app's behalf than it used to, in a way that compiles, ships, and only shows up as a slightly worse log entry months later. That's the same shape of risk every implicit default carries: it's free until the day it changes, and the fix is almost always the same one — write down what you actually need (error.value, not "whatever target happens to contain") instead of leaning on whatever the framework currently hands you.

Has a NestJS minor-version upgrade ever changed behavior you didn't know you were depending on? Drop it in the comments.

🎮 Try it yourself

▶️ Open the interactive playground →

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

🧠 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.

📚 Read next

🚀 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 Hacking Base64 With btoa(). toBase64() Fixes It Natively.

Parsa J — Thu, 05 Nov 2026 06:10:25 +0000

The feature was simple: let someone export a report and share it as a single link, PDF baked right in as a data URL. Worked first try. Worked in the demo. Worked for two weeks in production.

Then someone exported a 40-page report, and the share button threw:

RangeError: Maximum call stack size exceeded

Not a network error. Not a permissions error. The encoding step itself — the part of the code nobody had touched since the first version — blew the call stack on a PDF that was, by file standards, perfectly ordinary.

The code that worked right up until it didn't

async function shareReport(url) {
  const res = await fetch(url);
  const bytes = new Uint8Array(await res.arrayBuffer());
  const base64 = btoa(String.fromCharCode(...bytes));
  return `data:application/pdf;base64,${base64}`;
}

This is the pattern you'll find in half the Stack Overflow answers for "convert ArrayBuffer to base64 JavaScript." It reads fine. It passed code review. It's also a time bomb, and the fuse length depends on file size.

Before you keep reading: what do you think ...bytes is actually doing to String.fromCharCode?

It's not passing an array. String.fromCharCode doesn't take one — it takes a list of arguments, one per character code. The spread operator expands every single byte into its own argument in that function call. A 2KB test file is 2,000-ish arguments. Fine. A 40-page PDF is tens of thousands of bytes, which means tens of thousands of arguments in one call — and every JS engine caps how many arguments a function call can take. Cross that line and you don't get a graceful error, you get a stack blow-up with a message that tells you nothing about where it came from.

It gets worse with text, not just files

Swap the binary file for something simpler — base64-encoding a string for a shareable URL — and btoa() has a second failure mode:

btoa("Hello 👋 World");
// DOMException: Failed to execute 'btoa' on 'Window':
// The string to be encoded contains characters outside of
// the Latin1 range.

btoa() was never built to handle arbitrary text. Its actual contract is a "byte string" — every character has to map to a single byte, U+0000 through U+00FF. That range covers plenty of accented Latin letters (café and José actually encode fine, just not as UTF-8), but step outside it — an emoji, an em dash, a name with a character like Ł or a Cyrillic letter in it — and it's an instant throw.

The classic fix you'll find for this one is uglier than the bug:

btoa(unescape(encodeURIComponent(text)));

It works, in the sense that it doesn't throw. It also routes your string through unescape() — a function the spec deprecated decades ago and keeps around purely so this exact hack doesn't break the web. If you've ever wondered why base64-encoding a string in JavaScript feels like three functions wearing a trenchcoat, this is why: btoa() does one narrow job, and everything else is a workaround bolted on from outside.

Why both bugs have the same root cause

btoa() and atob() operate on strings, not bytes. Any time your actual data is binary — a fetched file, a crypto digest, Unicode text — you have to convert it into a byte-string-shaped JavaScript string first. That conversion step is where both bugs live: String.fromCharCode(...bytes) is how you build that string for binary data, and it's the one that blows the call stack. encodeURIComponent plus unescape is how you build it for Unicode text, and it's the one that's a deprecated-function sandwich.

The actual problem was never base64. It was the round trip through a string that base64 never needed in the first place.

🎮 Try it yourself

▶️ Open the interactive playground →

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

The fix: encode the bytes directly

As of late 2025, Uint8Array has two methods that skip the string entirely:

async function shareReport(url) {
  const res = await fetch(url);
  const bytes = new Uint8Array(await res.arrayBuffer());
  const base64 = bytes.toBase64(); // no spread, no stack limit
  return `data:application/pdf;base64,${base64}`;
}

One call. No String.fromCharCode, no spread, no argument-count ceiling, because nothing is being passed as individual arguments — toBase64() walks the bytes internally and hands back a string. Decoding mirrors it exactly:

const bytes = Uint8Array.fromBase64(base64);

For the text case, pair it with TextEncoder/TextDecoder instead of the unescape hack:

const base64 = new TextEncoder().encode("Hello 👋 World").toBase64();
const text = new TextDecoder().decode(Uint8Array.fromBase64(base64));
// text === "Hello 👋 World"

TextEncoder turns the string into UTF-8 bytes correctly — emoji, accents, anything — and toBase64() takes it from there. No deprecated functions, no silent mis-encoding.

The option you'll actually reach for: URL-safe tokens

Standard base64 uses + and /, both of which need escaping in a URL or a filename. toBase64() takes an alphabet option so you don't hand-roll the replacement:

const token = crypto.getRandomValues(new Uint8Array(16))
  .toBase64({ alphabet: "base64url", omitPadding: true });
// "Kx8pQ2v9mZt3dF7h..."  — safe to drop straight into a URL, no `+`, `/`, or `=`

omitPadding: true strips the trailing = characters too — the part that trips up anyone who's ever copy-pasted a base64 token into a query string and watched it get mangled.

The part worth being honest about

Uint8Array.prototype.toBase64() and Uint8Array.fromBase64() reached Baseline "newly available" in September 2025 — Chrome 140, Firefox 133, Safari 18.2, and the versions after. That's all three engines, not a single-vendor experiment, which is why it's worth adopting now rather than waiting. It is not in anything older than that, though, so if your app still supports last year's browsers, feature-detect before you rely on it:

const hasNativeBase64 = typeof Uint8Array.prototype.toBase64 === "function";

Keep your btoa/atob path behind that check for a while, rather than ripping it out the day you read this.

The report export, fixed

The 40-page PDF that used to crash the share button now encodes in one line, with no upper bound tied to how many arguments a function call can hold. The emoji that used to throw a DOMException round-trips cleanly through TextEncoder. Neither fix required a library — both were already shipping in the runtime, waiting for the hand-rolled version to get retired.

If you've still got a String.fromCharCode(...bytes) or an unescape(encodeURIComponent(...)) somewhere in your codebase, it's probably not broken yet. It's just waiting for a big enough file or a weird enough character. What's the oldest base64 hack still running in your production code — do you know what size file would finally break 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___

Running the meeting is a different job than being in one

Parsa J — Wed, 04 Nov 2026 06:10:55 +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 your second week owning the Tuesday planning sync, and forty minutes in, you notice the same two people have already agreed on the answer — you can see it in how they're not really asking each other questions anymore, just confirming — and everyone else is still taking turns giving their opinion like it's a vote that hasn't happened yet. You called this meeting. You're supposed to be running it. And you have absolutely no idea what to do with what you just noticed.

That's the actual job, and nobody tells you it's the job, because the invite just says "owner."

It's not the same skill as talking in one

You can be the person who speaks up well in a meeting — lands a point, asks the sharp question at the right moment — and still have no idea how to run one, because they're not the same muscle. Speaking in a meeting is about contributing to a conversation that's already happening. Running one is about deciding when the conversation is actually over, which is a much weirder thing to have to call.

Most meetings get decided before they start. Not maliciously — just structurally. Two people talk in a thread, or in the hallway, or on a call that wasn't this one, and by the time the room convenes, there's already an answer; the meeting itself is where that answer gets performed back as if it's being discovered live. Everyone plays along, partly out of politeness and partly because nobody wants to be the one who says "didn't we already decide this."

Your job, once you're the one running it, is to notice that moment and do something about it instead of letting the room keep performing.

The second audience nobody mentioned

There's a newer wrinkle on top of the old one. A lot of these meetings now have something else in the room besides people — a note-taker that's actually a model, quietly producing a transcript and a summary afterward. More people are skipping the meeting entirely and reading that summary instead, trusting it to carry the parts that matter. Which means the thing you're running isn't just for the people in the call anymore. It's also, increasingly, for whoever reads the write-up tomorrow and never heard the tone, the hesitation, the "well, I guess" that told you someone wasn't actually on board.

That changes what's worth saying out loud. A decision that only lives in the room's collective memory doesn't survive contact with a transcript built by something that can't hear hesitation. If it matters, it has to get said plainly enough to survive being summarized by a machine that wasn't paying attention to anything except words.

So what do you actually say?

Three moves, and all three are just different ways of naming the gap between what's being performed and what's actually true.

When you notice the room has converged and is still going through the motions: "I think we've converged — can I read that back as the decision?" Say the decision in one sentence. If nobody corrects it, the meeting is over, whatever's left on the agenda. If someone does correct it, good — you just found out it wasn't actually settled, which is useful information you didn't have thirty seconds ago.

When you suspect the question isn't really live anymore, and you want to check before you cut it off: "What would change your mind right now?" If the answer is a real thing — a number, a person's opinion, a test result — it's still open, keep going. If the answer is a shrug or a restatement of the same position, it was decided before you walked in, and you can say so without it being a jab at anyone.

When there's a side conversation happening in the room that's really a two-person problem wearing a group meeting as a costume: "Let's take that offline, the two of you, and bring back a recommendation." This does two things at once — it stops the rest of the room from sitting through a negotiation that isn't theirs, and it gives the two people involved somewhere to actually finish the thing instead of circling it in front of an audience.

And for the transcript problem specifically: "I'm going to say the decision out loud so it's actually in the notes, not just in our heads." It sounds almost silly to announce, but it's the sentence that turns a vague paragraph in tomorrow's AI summary into an actual decision someone can point back to in a month.

Where this goes wrong

Naming "I think we've converged" works when you have some standing to call it — when you're the one who convened the meeting, or you're a peer to the room. It does not work the same way when your manager, or your manager's manager, is in that room and the thing you'd be naming is that they've already decided something and are letting everyone else perform catching up to it. Say that sentence in that room and you're not running the meeting anymore, you're correcting someone with more leverage than you, in front of witnesses, and that's a different and much riskier act than the same sentence said to a group of peers. If you're junior and the decision-makers outrank you, the honest move is usually to ask the "what would change your mind" question privately, afterward, not to call the room out in it.

The transcript sentence has its own failure mode too — it can read as performing for the record rather than talking to the people in front of you, especially if you say it every single time. Use it when the decision is actually the kind that gets argued about later, not as a tic.

The part that isn't about skill

The person who ends up running these meetings is very often not the most senior person in the room — it's whoever's most organized, or whoever volunteered once and it stuck. That's worth saying plainly, because running a meeting well functions as leadership — you're the one deciding what counts as decided — but it doesn't always get recognized or compensated as leadership, especially if you came into the role sideways instead of through a title. You can do this job extremely well for a long time and have it read as "good at logistics" rather than "good at judgment," which is the same skill wearing a less flattering name.

And there's a quieter politics now too, with the note-taker in the room: who gets to see the raw transcript, whether it gets cleaned up before it's shared, whether someone's half-finished sentence becomes part of the permanent record of what they think. Nobody puts that in the meeting invite, but if you're the one running it, you're also, a little bit, the one deciding what gets to count as having been said.

Monday

Before your next recurring meeting, write down — just for yourself, two minutes, before anyone joins — which items on the agenda are actually open questions and which ones you already suspect are decided. Then say that split out loud at the top: "I think the first two are real decisions, the third one I suspect is already settled — tell me if I'm wrong." You're not performing authority. You're just telling the room what kind of meeting it's about to be, instead of making everyone find out the slow way.

📚 Read next

🚀 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.

getCurrentPosition() Has No Default Timeout. That's the Trap.

Parsa J — Wed, 04 Nov 2026 06:10:24 +0000

The ticket read: "location button sometimes just spins forever." Not a crash, not an error toast — just a spinner that never stopped. QA couldn't reproduce it. It worked every time on the office Wi-Fi, every time on a laptop, every time in the demo to the client.

It only happened out in the field. On a phone. Somewhere the GPS fix took its time and the Wi-Fi-based positioning fallback was slow to answer. Which meant it was exactly the one environment nobody tested in before shipping.

Here's the part that made it worse: the code had an error handler. Both arguments to getCurrentPosition() were filled in, success and failure. By every code-review instinct, this was handled.

The code that looks fully handled

function useMyLocation(onFound, onFail) {
  navigator.geolocation.getCurrentPosition(
    (pos) => onFound(pos.coords),
    (err) => onFail(err.message)
  );
}

A success callback, an error callback, nothing swallowed. If you squint, it even looks defensive — most getCurrentPosition() snippets you'll find in the wild look exactly like this.

Before you keep reading: what has to happen for that error callback to fire at all? Not "what does it do" — when does the browser decide to call it?

The honest answer is: only when the browser gives up and reports a GeolocationPositionError — permission denied, position unavailable, or a timeout. And a timeout is an option you pass in. If you don't pass one, there's nothing to time out. The browser just... keeps trying. Forever, if it has to. Neither callback is under any obligation to ever run.

The default timeout is not "some reasonable number." It's `Infinity`.

getCurrentPosition() takes a third, optional options argument: { enableHighAccuracy, timeout, maximumAge }. Skip it — like the snippet above does — and you get the spec's own defaults:

{ enableHighAccuracy: false, timeout: Infinity, maximumAge: 0 }

timeout: Infinity means precisely what it says: the call will wait as long as the device needs to produce a position, with no upper bound. On a laptop with recent Wi-Fi positioning data cached nearby, that's near-instant, so the bug never shows up in testing. On a phone with a weak signal indoors, "as long as it needs" can be minutes — or, if the underlying location provider never calls back at all, forever. There's no silent fallback, no eventual error. The spinner you built to show while waiting just keeps being accurate.

The other default nobody reads: `maximumAge: 0`

maximumAge controls whether the browser is allowed to hand back a cached position instead of asking the device for a brand-new fix. The default is 0 milliseconds — meaning no cache is old enough to use, ever. Every single call to getCurrentPosition(), even one fired a hundred milliseconds after the last one, forces a fresh GPS/Wi-Fi/cell fix from scratch.

That's rarely what you actually want. A "locate me" button a user double-clicks, or a component that calls getCurrentPosition() on mount right after a sibling component just did the same thing, don't need two independent fixes a tenth of a second apart. Passing a real maximumAge — "a position up to 30 seconds old is fine" — turns repeat calls into near-free cache hits instead of two full location requests:

navigator.geolocation.getCurrentPosition(onFound, onFail, {
  timeout: 10_000,
  maximumAge: 30_000,
});

`watchPosition()` has the same shape of bug as a forgotten `clearInterval`

getCurrentPosition() asks once. watchPosition() asks continuously, calling your success callback every time the device's position changes meaningfully — useful for live tracking, useless the moment nobody's watching the screen anymore. It returns a watch ID, and that ID is your responsibility:

const watchId = navigator.geolocation.watchPosition(onMove, onError, {
  enableHighAccuracy: true,
});

// later, when you're done:
navigator.geolocation.clearWatch(watchId);

Skip that last line — the same way it's easy to skip clearInterval() — and the watch keeps running after the component that started it is gone. In a React component, that's a watchPosition() call in a useEffect with no cleanup function: the GPS radio stays active, the callback keeps firing into a component that no longer exists, and the battery drain shows up in a support ticket that has nothing to do with location on its face.

useEffect(() => {
  const id = navigator.geolocation.watchPosition(onMove, onError);
  return () => navigator.geolocation.clearWatch(id);
}, []);

One line in the cleanup function. Easy to write, easy to forget, and nothing in the API warns you that you forgot it.

It's not a Promise, and that's the last gotcha

getCurrentPosition() predates fetch(), predates Promise, and was never updated to support either — it's success/error callbacks, full stop. You can't await it directly. The fix is a wrapper you write once and reuse everywhere:

function getPosition(options) {
  return new Promise((resolve, reject) => {
    navigator.geolocation.getCurrentPosition(resolve, reject, {
      enableHighAccuracy: false,
      timeout: 10_000,
      maximumAge: 30_000,
      ...options,
    });
  });
}

try {
  const pos = await getPosition();
  useLocation(pos.coords);
} catch (err) {
  if (err.code === err.PERMISSION_DENIED) showPermissionHelp();
  else if (err.code === err.TIMEOUT) showRetry();
  else showGenericError();
}

Every default that bit the original snippet is now an explicit choice, and the whole thing reads top to bottom instead of nesting two callbacks inside each other.

The one real constraint: it needs a secure origin

This part isn't a trap, just worth stating plainly: every major browser requires a secure context — HTTPS, or localhost in development — before it will even ask for location permission. That's been true for close to a decade now, not a new restriction, and there's no workaround or flag to reach for; if a getCurrentPosition() call is silently failing in a way none of the above explains, check the protocol in the address bar first.

🎮 Try it yourself

▶️ Open the interactive playground →

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

The playground above simulates the GPS fix with a slider, so you get the exact same race every time instead of waiting on whatever signal your actual device has right now. Set a slow "fix," turn on "use the default options," and watch the stopwatch climb with nothing to stop it — that's timeout: Infinity, reproduced on demand. Then try the watchPosition() panel: start it, hit "simulate component unmount" without stopping it first, and watch the counter keep climbing anyway.

🧠 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.

The fix for that "spins forever" ticket was three lines: a timeout, a maximumAge, and a clearWatch() in a cleanup function that had never been written. None of it was hard once someone knew to look for it — the hard part was realizing that "sometimes it just hangs" wasn't a flaky bug report. It was the spec's own default, read literally.

Does your codebase have a bare getCurrentPosition() call anywhere without a timeout? Worth a five-minute grep before it becomes someone else's "impossible to reproduce" ticket.

📚 Read next

🚀 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 Canvas Is Freezing the Page. OffscreenCanvas Fixes That.

Parsa J — Tue, 03 Nov 2026 06:10:56 +0000

You open the profiler, record a session, and the flame chart looks great. 60 frames a second, steady, no dropped frames. You ship it.

Then someone clicks a button while the animation is running, and for half a second, nothing happens. Not a dropped frame — the whole page. The click just sits there, queued, waiting for a thread that's busy painting pixels nobody asked it to interrupt.

Here's the part that doesn't show up in a frame-rate graph: your canvas animation was never competing with itself. It was competing with every click handler, every layout pass, every bit of input handling on the page — because by default, all of that runs on exactly one thread, and canvas drawing calls are first-class citizens on it.

The fix everyone reaches for first

The instinct is to blame the math. Heavy canvas work — thousands of particles, a live chart redrawing every tick, a game loop doing collision checks — looks like a computation problem, so people reach for a Web Worker to do the computation off-thread.

// main.js
const worker = new Worker("particles-worker.js");
worker.postMessage({ type: "tick" });
worker.onmessage = (e) => {
  const positions = e.data.positions;
  // ...now draw them, back on the main thread
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  for (const p of positions) ctx.fillRect(p.x, p.y, 2, 2);
};

This genuinely helps — the position math moves off the main thread. But watch what's still happening in that onmessage handler: clearRect, fillRect, every actual drawing call, is still running on the main thread, because that's the only thread with access to the <canvas> element's rendering context. You moved the arithmetic. You didn't move the part that was actually fighting your clicks for time.

The part that's easy to miss: drawing itself blocks the page

A <canvas> element's 2D or WebGL context has always been tied to the DOM, and anything tied to the DOM only exists on the main thread. That's not a performance detail, it's a structural one: a worker has no document, so it has never been able to hold a canvas context at all — until there was a way to give it one that isn't attached to the page.

That's what OffscreenCanvas is. Not a faster canvas. A canvas whose rendering context can live somewhere other than the main thread, so the fastest possible canvas is one where the drawing calls stop queuing up behind your click listeners in the first place.

The fix: move the context itself into the worker

<canvas id="scene" width="600" height="400"></canvas>

// main.js
const canvas = document.getElementById("scene");
const offscreen = canvas.transferControlToOffscreen();
const worker = new Worker("render-worker.js");
worker.postMessage({ canvas: offscreen }, [offscreen]);

// the main thread still owns input — forward what the worker needs
canvas.addEventListener("pointermove", (e) => {
  worker.postMessage({ type: "pointer", x: e.offsetX, y: e.offsetY });
});

// render-worker.js
let ctx;
let pointer = { x: 0, y: 0 };

self.onmessage = (e) => {
  if (e.data.canvas) {
    ctx = e.data.canvas.getContext("2d");
    requestAnimationFrame(loop);
  }
  if (e.data.type === "pointer") pointer = e.data;
};

function loop() {
  ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
  ctx.beginPath();
  ctx.arc(pointer.x, pointer.y, 20, 0, Math.PI * 2);
  ctx.fill();
  requestAnimationFrame(loop);
}

transferControlToOffscreen() detaches the canvas element from its own rendering context and hands you an OffscreenCanvas you can transfer to a worker like any other transferable object. Inside the worker, getContext("2d") gives back something that draws almost exactly like the context you're used to — same fillRect, same beginPath, same drawImage — except every one of those calls now runs on a thread that has nothing else to do but draw.

The one thing that doesn't come along for free is input. A worker has no DOM, so it can't attach its own pointermove or click listeners to anything. The main thread stays the one place that owns events, and your job is to forward the few fields the worker actually needs — as shown above, just x and y, not the whole event object, which isn't transferable anyway.

Why the page stays responsive now

Open two tabs in your head. In the first, with everything on the main thread, a click has to wait in the same queue as every pending fillRect call — if the canvas is mid-frame, the click waits for the frame to finish. In the second, with OffscreenCanvas, the canvas's frame is happening on a different thread entirely. The main thread's event queue is short again, because the one thing that used to dominate it moved out.

This is the distinction worth sitting with: OffscreenCanvas doesn't make your particle system compute faster, and it doesn't raise your frame rate. It makes the main thread's queue shorter by taking an entire category of work out of it. A canvas that was drawing 10,000 particles at 60fps before will still be drawing 10,000 particles at roughly 60fps after — the difference is that a click, a keypress, or a scroll now gets handled in the same frame instead of after it.

🎮 Try it yourself

▶️ Open the interactive playground →

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

When the main thread was fine all along

Not every canvas needs this. A sparkline that redraws once when new data arrives, a static chart, an icon you draw once on mount — none of that is holding the main thread hostage, because none of it is running every frame. The tell isn't "I use canvas," it's "my canvas work and my users' clicks are both trying to happen right now, repeatedly, for as long as the page is open." Games, live data visualizations, drawing tools, anything with a requestAnimationFrame loop that runs indefinitely — that's the category where this earns its complexity.

It's also not free complexity. You lose direct DOM access inside the worker, so anything that reads layout, measures text against real fonts in edge cases, or needs synchronous access to other page state has to be designed around message passing from the start, not bolted on later.

Is this safe to ship today?

Yes. Chrome has supported OffscreenCanvas since 2018, Firefox enabled it for workers a few years after that, and Safari was the last to land it, in Safari 16.4 in March 2023. All three major engines have carried it for a while now, so there's no meaningful fallback story you need to write — check "OffscreenCanvas" in window if you want a belt-and-suspenders guard, but you're unlikely to need it.

The next time a profiler shows you a perfectly smooth 60fps canvas sitting on top of a page that still stutters when someone clicks, you'll know the frame rate was never the number that mattered.

What's the heaviest thing you're currently drawing to a <canvas> on the main thread? I'm curious how many of you are one transferControlToOffscreen() call away from fixing a bug you've been blaming on something else.

🧠 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.

📚 Read next

🚀 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 16.4 ensureStatic: Locking Routes Fully Static

Parsa J — Tue, 03 Nov 2026 06:10:25 +0000

You ship a route you're sure is fully static. A teammate adds one fetch() call to a shared layout three weeks later — no cache directive, just a quick lookup they needed for a banner. Nothing errors. The build succeeds. The route still "looks" static in dev. It isn't anymore: that one call now forces the whole subtree to render on every request, and nobody notices until the latency dashboard does.

This is written against Next.js 16.4.3 (verified against the framework's own GitHub release notes and documentation as of October 2026). The guardrail for exactly this scenario — ensureStatic — was stabilized in 16.4.0, after shipping unstable for a few releases. This series mentioned it in passing two weeks ago; this episode is the first real look at what it actually checks, and what it refuses to let you ship.

What you'll learn

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

Explain what ensureStatic actually guarantees, and why "the page renders fast in dev" isn't the same guarantee
Pick the right level — 'shell', 'prefetch', or 'navigation' — for a given route
Predict exactly which build failures ensureStatic = 'navigation' will produce, before you hit them
Apply the inheritance rules correctly across layouts, nested segments, and parallel routes
Tell ensureStatic apart from instant, a different, dev-time-only check with a similar name

Who this is for: you're comfortable with the App Router and Server Components, and you've enabled Cache Components (cacheComponents: true) or are about to. If "use cache", cacheLife(), and the App Shell are new to you, this series' Cache Components Explained and Instant Navigations: How Partial Prefetching Works cover the pieces ensureStatic builds on — worth reading first, not required before this one makes sense.

The problem: "static" with no guarantee
The mental model: four levels, one escalating promise
Staged walkthrough: shell, then prefetch, then navigation
What 'navigation' actually validates
Edge cases and inheritance rules
ensureStatic vs instant
Best practices
FAQ
Cheat sheet
Key takeaways

The problem: "static" with no guarantee

Say you run a documentation site. Every page lives under a shared layout — header, sidebar nav, footer — and the page content itself is cached:

// app/docs/layout.tsx — looks static, isn't guaranteed to stay that way
export default function DocsLayout({ children }: { children: React.ReactNode }) {
  return (
    <div className="docs-shell">
      <Header />
      <Sidebar />
      <main>{children}</main>
    </div>
  )
}

// app/docs/[slug]/page.tsx
async function getDoc(slug: string) {
  "use cache"
  return db.docs.findBySlug(slug)
}

export default async function DocPage({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  const doc = await getDoc(slug)
  return <Article doc={doc} />
}

This is genuinely fast today. Nothing in the visible code is wrong. But nothing here asserts that it stays fast. Three weeks later someone adds a personalized "you're on the free plan" banner to <Header />, reading a cookie with a plain fetch to an account API — no "use cache", because it's "just a header, it's small." That one read makes the header request-scoped, which makes the layout request-scoped, which pulls every page under app/docs/ back to rendering per request. The build still succeeds. Nothing in the PR review catches it, because the diff is three lines in a component nobody thinks of as "the caching layer."

ensureStatic exists so that instead of discovering this in a latency graph, you discover it as a build failure, pointing at the exact file and the exact API call that broke the guarantee — the moment it's introduced, not the moment someone notices the site got slower.

The mental model: four levels, one escalating promise

ensureStatic is a route segment config — exported from a page.tsx or layout.tsx, the same place you'd put dynamic or revalidate in the Pages Router-era App Router code. It requires Cache Components (cacheComponents: true) to be enabled; without it, exporting ensureStatic fails the build outright rather than doing nothing.

type EnsureStatic = 'auto' | 'shell' | 'prefetch' | 'navigation' | false

Each value names a different amount of the route's navigation lifecycle that must be static — and that lifecycle is the same one last episode's App Shell and Partial Prefetching work defines:

A default <Link> (no prefetch prop) loads the App Shell — the parts of the route that don't depend on URL data.
<Link prefetch={true}> also resolves that specific link's URL-dependent data ahead of the click.
The actual navigation renders whatever is left after someone clicks.

Value	What must be static
`'auto'` (default — same as omitting the export)	Nothing extra required
`'shell'`	The App Shell loaded by a plain `<Link>`
`'prefetch'`	The App Shell and every per-link prefetch
`'navigation'`	The complete rendered route, including what streams in after the click
`false`	No requirement — and it blocks child segments from requiring one either

Read it as an escalating promise: 'shell' is the cheapest to satisfy (it only constrains what's shared across every route under that layout), 'navigation' is the strongest (it constrains the entire page, every time, for everyone). 'shell' and 'prefetch' only mean anything when Partial Prefetching is on — without it there's no separate shell stage to pin down, so 'shell' quietly does nothing and logs a warning. 'navigation' is different: it only needs Cache Components, not Partial Prefetching, because it's asserting something about the full render, not about a separate shell stage.

Staged walkthrough: shell, then prefetch, then navigation

Take a small storefront: a cart layout shared by everything, product pages, and static buying guides.

Step 1 — lock the shell. The cart layout reads a cookie to show an item count — personalized, so it can't be part of the shell. Wrap it in <Suspense> with a static fallback, then assert the rest of the layout stays shell-eligible:

// app/(store)/layout.tsx
export const ensureStatic = 'shell'

export default function StoreLayout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <nav>
        <Logo />
        <Suspense fallback={<CartBadge count={null} />}>
          <CartCount /> {/* reads a cookie — fine, it's inside Suspense */}
        </Suspense>
      </nav>
      {children}
    </>
  )
}

If anyone later moves cookie-reading code above that Suspense boundary — directly into StoreLayout — the build fails immediately, naming the offending file. That's the whole point: the mistake from the earlier docs example gets caught here instead of in production.

Step 2 — lock prefetch. Product pages are cached with "use cache", but the "in your cart" badge on each product card is personalized. ensureStatic = 'prefetch' on the product list route asserts every one of those per-link prefetches resolves to static output — so hovering over twenty product cards doesn't fire twenty personalized round-trips:

// app/(store)/products/page.tsx
export const ensureStatic = 'prefetch'

async function getProducts() {
  "use cache"
  cacheLife({ stale: 300, revalidate: 3600, expire: 86400 })
  return db.products.findAll()
}

Step 3 — lock full navigation. Buying guides are plain marketing content — no personalization, no request-time data, ever. That's the one case worth the strongest guarantee:

// app/(store)/guides/[slug]/page.tsx
export const ensureStatic = 'navigation'

export async function generateStaticParams() {
  const guides = await db.guides.findAllSlugs() // must enumerate every slug
  return guides.map((g) => ({ slug: g.slug }))
}

async function getGuide(slug: string) {
  "use cache"
  cacheLife({ stale: 3600, revalidate: 86400, expire: false })
  return db.guides.findBySlug(slug)
}

Here the whole page — not just a shared layout slice — must render to static output, for every one of the slugs generateStaticParams returns.

What `'navigation'` actually validates

'navigation' is the level worth understanding precisely, because it's the one that turns real mistakes into real build errors instead of silent regressions. With cacheComponents on, exporting ensureStatic = 'navigation' from a page makes the build (and the dev server) reject:

Uncached data — a bare fetch() or database call with no "use cache" wrapping it, and connection() (the explicit "this must be dynamic" escape hatch)
Runtime-only APIs — cookies(), headers(), or searchParams read on the server
Cache entries that are effectively dynamic anyway — "use cache" with an expire under five minutes, a stale under 30 seconds, or revalidate: 0; a cache that invalidates that fast isn't meaningfully static
Request-dependent promises passed into a Client Component — even if the server code itself looks cached, handing a promise whose value depends on the current request across the server/client boundary reintroduces a per-request dependency

Dynamic segments must also export a generateStaticParams() that returns the complete set of params — a partial list isn't enough once you've promised the whole route is static. The same constraints apply to generateMetadata and generateViewport, since metadata generated from a live cookies() read would just as quietly break the promise.

Edge cases and inheritance rules

A few rules exist specifically to stop you from creating a guarantee that only holds in one place:

A child segment can tighten freely, but can't explicitly downgrade. A layout exporting 'shell' can have a page under it export 'navigation' (stronger) — that builds fine. Exporting 'auto' on that same page also builds fine: 'auto' is always treated as "no opinion," so it never conflicts with an ancestor's value — the layout's 'shell' requirement just keeps applying to the page underneath it. What actually fails the build is a child exporting a weaker concrete level than an ancestor already set, e.g. a page exporting 'shell' under a layout that requires 'navigation' — that's a real contradiction, not a deferral, and Next.js rejects it by name.
false and a level don't mix in the same tree. If a parent is false and a child tries to set 'shell', the build fails — false isn't "no opinion," it's an explicit "nothing here is required to be static," and a child can't retroactively impose a requirement its parent already waived.
Parallel routes rendered together must agree. If two parallel slots render side by side, they must all share the same ensureStatic value, leave it unset, or use 'auto' — one slot can't be 'navigation' while its sibling is 'shell'.
A value applies to the whole route it's exported from, parent layouts included — exporting it from a deep page doesn't exempt the layouts above it from the same requirement.

`ensureStatic` vs `instant`

They sound similar and ship in the same release, which invites confusing them. They check different things:

ensureStatic is a build-time (and dev-time) enforcement. Export it, and the build fails if the promise doesn't hold. It's a contract.
instant is a dev-time signal, not an enforced contract — it's a way to see, during development, whether a given navigation would paint instantly under the current code, without failing your build if it wouldn't.

Use instant while you're exploring which routes are candidates for a stronger guarantee. Use ensureStatic once you've decided one of them needs that guarantee enforced going forward, not just observed today.

Best practices

Start at 'shell' on your root and section layouts, not 'navigation' on every page — the shell is shared infrastructure, and locking it first catches the highest-leverage mistakes (a stray cookie read in a header) for the least ongoing cost.
Reserve 'navigation' for routes that are genuinely public and non-personalized — marketing pages, docs, buying guides. Forcing it onto a route that legitimately needs request-time data just means fighting the build instead of fixing the model.
Add it when a route is already correct, not to force it correct. ensureStatic is a regression guard, not a refactoring tool — get the caching right first with "use cache" and cacheLife(), confirm it behaves, then lock it in.
Treat a new ensureStatic build failure as a real signal, not an obstacle. It is almost always telling you that something just became request-scoped that your team didn't intend to make request-scoped.
Don't apply 'prefetch' to a route with dozens of simultaneously-visible links unless the per-link data is genuinely cheap and cached — it's an opt-in cost, not a free upgrade from 'shell'.

FAQ

Does ensureStatic work without Cache Components?
No. It requires cacheComponents: true; exporting it without that flag fails the build rather than silently doing nothing.

Can I export ensureStatic from a Client Component?
No — doing so throws an error. It's a server-side route segment config, like dynamic or revalidate before it.

Does 'shell' do anything if I haven't enabled Partial Prefetching?
No. 'shell' and 'prefetch' only have teeth once Partial Prefetching is on — without it, Next.js logs a warning and the export has no effect. 'navigation' doesn't have this dependency; it works from Cache Components alone.

What if I only want to guard one slow subtree, not the whole route?
ensureStatic is a whole-route (or whole-layout) assertion. For a single subtree, the docs point to deferring it explicitly with await prefetch() (skip it during link prefetch) or await navigation() (skip it until the click) instead of reaching for a route-level export.

Is this the same as the old export const dynamic = 'force-static'?
No, and this is the important distinction. force-static (and dynamic generally) sets the rendering mode for the entire route as one unit, pre-Cache-Components. ensureStatic is built for a world where one route can legitimately mix prerendered, cached, and request-time content — it asserts a static guarantee over a specific slice (shell, prefetch, or full navigation) of a route that's otherwise allowed to be mixed.

Will I hit this if I'm still on Next.js 15?
No — ensureStatic is a 16.4+ API, and it depends on Cache Components, which itself isn't the default until a later major. On 15.x, write around it rather than approximating it with force-static, which doesn't carry the same per-slice guarantee.

🎮 Try it yourself

▶️ Open the interactive playground →

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

Cheat sheet

ensureStatic values (route segment config, requires cacheComponents: true):

  'auto'        — default, same as omitting the export. No extra requirement.
  'shell'       — the App Shell (needs Partial Prefetching; else: warning, no-op)
  'prefetch'    — App Shell + every per-link prefetch (needs Partial Prefetching)
  'navigation'  — the full rendered route (Cache Components alone is enough)
  false         — no requirement; blocks children from requiring one

'navigation' build fails on:
  • fetch()/db call with no "use cache"        • cookies() / headers() / searchParams
  • connection()                                • use cache with expire < 5m, stale < 30s, or revalidate: 0
  • request-dependent promise passed to a Client Component
  • dynamic segment missing a complete generateStaticParams()

Inheritance:
  • child can set a stronger concrete level freely (shell → prefetch → navigation)
  • child exporting 'auto' is always compatible — defers to the ancestor's level, never fails the build
  • child exporting a weaker CONCRETE level than an ancestor already set → build fails
  • false + a level in the same tree → build fails
  • parallel routes rendered together must share the same value (or 'auto'/unset)

Not the same as: dynamic = 'force-static' (whole-route, pre-Cache-Components)
Not the same as: instant (dev-time signal, not an enforced build contract)

🧠 Test yourself

Think it clicked? Take the 10-question quiz →

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

Key takeaways

ensureStatic turns "I'm pretty sure this route is static" into something the build actually checks, with four levels of increasing strength: 'auto', 'shell', 'prefetch', 'navigation'.
It requires Cache Components; 'shell' and 'prefetch' additionally require Partial Prefetching, while 'navigation' stands on Cache Components alone.
'navigation' validates specifically: no uncached fetches, no runtime APIs, no short-lived cache entries, no request-scoped promises crossing into Client Components, and a complete generateStaticParams().
A child can freely set a stronger level, and 'auto' on a child never conflicts — but explicitly exporting a weaker concrete level than an ancestor already set fails the build, and parallel routes rendered together must agree.
It's a regression guard for routes you've already made static, not a tool for making them static — and it's a different thing entirely from the dev-time instant signal.

That cookie read someone adds to a shared header three weeks from now doesn't have to be a latency regression you discover in a dashboard. With ensureStatic on the layout it depends on, it's a build failure with your name on the stack trace — which is a much better place to find it.

📚 Read next

🚀 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___

Vue provide/inject: Why You Should Never Skip readonly()

Parsa J — Mon, 02 Nov 2026 05:32:04 +0000

A teammate asks you why cart.total changed. You open the component that renders it — nothing there mutates it. You check its parent — nothing there either. Twenty minutes later you find it: a <PromoBanner> three levels down, nowhere near the cart, called cart.items.push(...) because it had a reference to the object and nobody stopped it. Vue didn't do anything wrong. provide/inject handed that component the exact same reactive object the cart store holds, and JavaScript let it write to what it was handed. The bug isn't in Vue's reactivity — it's in a contract nobody enforced.

What You'll Learn

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

Explain why an injected value is a live reference, not a snapshot or a message
Reproduce the "mutation from anywhere" bug on purpose, so you recognize it in a real codebase
Apply Vue's own fix — readonly() on the provided value, paired with an exposed mutator function — and know exactly what it does and doesn't stop
Type provide/inject with InjectionKey<T> so TypeScript catches a missing provider at compile time
Decide when provide/inject is still the right tool and when a store (Pinia) earns its weight

Who this is for: you've used ref, reactive, and basic provide/inject in a Vue 3 Composition API app, and you want the version of this pattern that survives more than two components.

Why this breaks: provide/inject shares the object, not a copy
The mental model
The fix: readonly() and a mutator function
Typing it with InjectionKey
Edge cases and gotchas
Best practices
FAQ
Cheat sheet
Key takeaways

This is written against Vue 3.5 (verified 3.5.44 on npm's latest tag, October 2026). Everything here is Composition API with <script setup>; there is no Options API equivalent worth writing, since this.$options.provide was always the weaker version of this same idea.

Why this breaks: provide/inject shares the object, not a copy

Here's the setup almost every provide/inject tutorial shows, including Vue's own introductory example:

<!-- CartProvider.vue -->
<script setup>
import { reactive, provide } from "vue";

const cart = reactive({ items: [], total: 0 });

function addItem(item) {
  cart.items.push(item);
  cart.total += item.price;
}

provide("cart", cart);
provide("addItem", addItem);
</script>

<!-- PromoBanner.vue, three components deep -->
<script setup>
import { inject } from "vue";

const cart = inject("cart");

function applyFreeGift() {
  // "I just need to add one thing, calling addItem felt like overkill"
  cart.items.push({ id: "free-sticker", price: 0 });
}
</script>

Run this and it works. cart.items updates, the cart badge re-renders, nothing throws. That's exactly why it's dangerous: there is no error to notice, no test that fails, no lint rule that fires. inject("cart") returned the same reactive() proxy the provider created — not a message describing a change, not a frozen snapshot — the object itself. Anything with a reference to it can write to it, from anywhere in the tree, and Vue's reactivity system will faithfully propagate that write, because propagating writes is its entire job.

The bug only shows up later, as a debugging problem: cart.total is wrong, or cart.items has an entry nobody can explain, and the mutation could be coming from any of the components that called inject("cart"). Vue devtools' state inspector will show you the current value, but it won't point you at the nine places across the tree that are allowed to change it.

The mental model

The mental model: provide/inject is Vue's version of passing a reference down an arbitrarily deep call stack — it shares the exact object, with none of the access control a function's parameters would give you. A prop is already a one-way, shallow-readonly-by-convention handoff that Vue warns about if you mutate it directly. provide/inject has no equivalent warning built in, because the whole point of the API is to skip the explicit, typed handoff of props — and that convenience is also the hole.

Vue's own guide is explicit about the fix, and about whose job it is: "it is recommended to keep any mutations to reactive state inside of the provider whenever possible," and when a descendant genuinely needs to change something, the provider should expose "a function that is responsible for mutating the state" rather than the state's writable surface. That single line is doing a lot of work, and it's easy to skip because unlike a type error, skipping it doesn't break anything today.

The fix: readonly() and a mutator function

The fix is two changes to the provider, and zero changes to how descendants read the value.

<!-- CartProvider.vue -->
<script setup>
import { reactive, readonly, provide } from "vue";

const cart = reactive({ items: [], total: 0 });

function addItem(item) {
  cart.items.push(item);
  cart.total += item.price;
}

// Descendants get a read-only view of the state...
provide("cart", readonly(cart));
// ...and the only sanctioned way to change it.
provide("addItem", addItem);
</script>

Now the PromoBanner from earlier doesn't quietly succeed:

const cart = inject("cart");
cart.items.push({ id: "free-sticker", price: 0 });
// [Vue warn] Set operation on key "0" failed: target is readonly.
// [Vue warn] Set operation on key "length" failed: target is readonly.

readonly() wraps the value in a second proxy that intercepts writes and, in development, logs a warning naming the exact key that was targeted instead of silently applying — Vue's reactivity docs show this same message for a plain mutation attempt on a readonly() copy of a reactive object. The write doesn't happen; the original, writable cart inside the provider is unaffected. PromoBanner has no way to change the cart except by calling the addItem function it was also given — which means every mutation path is now a named function you can grep for, breakpoint, or log.

Key concept: readonly() doesn't make the data immutable — the provider can still mutate its own cart freely. It makes the injected reference refuse writes, which is what turns "any of nine components might have done this" back into "only addItem could have done this."

readonly()'s wrapping is deep: nested objects and arrays reached through the readonly proxy are themselves readonly, so cart.items.push(...) is caught, not just reassigning cart.items itself. If you only need the top level protected (rare, and usually a sign the shape should be flatter), shallowReadonly() exists, but reach for plain readonly() by default — a one-level gap is exactly where the next PromoBanner finds the one key that still writes.

Typing it with InjectionKey

String keys ("cart") work but give TypeScript nothing to check — a typo in the key, or injecting before the provider ever renders, both fail silently at runtime. InjectionKey<T> fixes both:

// keys.ts
import type { InjectionKey, DeepReadonly } from "vue";

export interface CartState {
  items: { id: string; price: number }[];
  total: number;
}

// Keyed as DeepReadonly<CartState>, because that's what provide(cartKey, readonly(cart))
// actually hands out — typing it as plain CartState fails to compile, since readonly()'s
// nested readonly arrays aren't assignable to CartState's mutable ones.
export const cartKey: InjectionKey<DeepReadonly<CartState>> = Symbol("cart");
export const addItemKey: InjectionKey<(item: CartState["items"][number]) => void> =
  Symbol("addItem");

// CartProvider.vue <script setup lang="ts">
import { reactive, readonly, provide } from "vue";
import { cartKey, addItemKey, type CartState } from "./keys";

const cart = reactive<CartState>({ items: [], total: 0 });
function addItem(item: CartState["items"][number]) {
  cart.items.push(item);
  cart.total += item.price;
}

provide(cartKey, readonly(cart));
provide(addItemKey, addItem);

// PromoBanner.vue <script setup lang="ts">
import { inject } from "vue";
import { cartKey, addItemKey } from "./keys";

// cart: DeepReadonly<CartState> | undefined — TypeScript now forces you to
// handle the "no provider" case instead of finding it at 2am.
const cart = inject(cartKey);
const addItem = inject(addItemKey);

The symbol key means a typo can't collide with an unrelated provide("cart", ...) elsewhere in the tree, and inject()'s return type is now narrowed to DeepReadonly<CartState> | undefined — the undefined is real, because inject without a default genuinely returns undefined when there's no matching provider above the component, and the type system now makes you prove you've considered that.

Edge cases and gotchas

readonly() on a ref warns the same way. provide("count", readonly(count)) means inject("count").value = 5 from a descendant logs the same "target is readonly" warning instead of applying. The pattern isn't specific to reactive() objects.
computed() needs no wrapping. A computed ref is already read-only by construction — assigning to .value is a TypeScript error (or a runtime no-op without a custom setter) regardless of readonly(). If the provided value is derived, not stored, provide the computed() directly.
The provider can still forget the function. readonly() stops the descendant from writing; it does nothing if the provider itself exports a mutable reference alongside the readonly one by mistake. The discipline is "provide state read-only, provide every allowed change as a named function" — both halves matter.
This is a dev-mode warning, not a runtime guarantee you should rely on for security. It protects you from accidental mutation in your own codebase, not from a determined caller bypassing Vue's proxy in production. Don't use it as an access-control boundary for untrusted code.
It's the single-request version of the shared-state trap. The same "one object, many writers" shape that bites provide/inject across a component tree also bites module-scope state across requests on a Vue SSR server — that's a different failure mode with a different fix, covered in this series' composables shared-state piece.

Best Practices

Reach for provide/inject (with this pattern) when the state is genuinely tree-scoped — a form wizard's shared step state, a modal's context, a design-system component's configuration — and you want to avoid prop-drilling it through components that don't care about it.

Pair every provide() of mutable state with:

readonly() (or shallowReadonly()) around the value itself.
One or more named functions for every change a descendant is allowed to make.
An InjectionKey<T> instead of a string, once more than one file touches the key.

Reach for Pinia instead when the state needs to be read or changed from components that aren't descendants of a single provider — a cart that's also read from the header nav and a checkout page outside that subtree, for instance. provide/inject is scoped to a component subtree by design; a store isn't. Using provide/inject for truly global, cross-tree state usually means re-providing it near the root anyway, at which point a store does the same job with less wiring.

FAQ

Does readonly() also stop the provider from mutating the value?

No. readonly(cart) returns a new proxy; the original cart reference the provider holds is still the plain reactive() object, fully writable. Only the reference that goes through provide() is wrapped.

Does wrapping a large object in readonly() cost performance?

The wrapping itself is cheap — it's a proxy, created once, not a deep clone. Reads are tracked the same way reactive() reads are. You won't notice this on anything short of a very large, deeply nested object being read in a tight loop, and that's a different problem to measure separately.

Can a child still mutate the state through a method it calls?

Yes, and that's correct, not a hole. If the provider exposes addItem(), a child calling addItem() is mutating state through the one sanctioned path — that's the entire point. readonly() blocks direct property writes on the injected value; it was never meant to block the mutator functions you provide alongside it.

Does this replace Pinia?

No — it's the right tool for state scoped to one part of the tree, not a general store replacement. See "Best practices" above for the line between them.

What happens if a component injects a key with no matching provider?

Without a default, inject() returns undefined at runtime. With InjectionKey<T>, TypeScript types that return as T | undefined, so a missing provider becomes a type error you fix during development instead of a crash a user finds. You can also pass a default as inject(key, defaultValue).

Cheat Sheet

Task	Code	Notes
Provide read-only state	`provide(key, readonly(state))`	Deep by default; descendants can read, not write
Provide the allowed mutation	`provide(mutateKey, mutateFn)`	One named function per allowed change
Type the key	`const key: InjectionKey<T> = Symbol("x")`	`inject(key)` is now typed `T \
Inject with a safe default	{% raw %}`inject(key, fallback)`	Avoids `undefined` entirely when a sane default exists
Top-level-only protection	`shallowReadonly(state)`	Rare — nested objects stay mutable
Readonly a single ref	`provide(key, readonly(myRef))`	Same warning-on-write behavior as an object

// keys.ts
import type { InjectionKey, DeepReadonly } from "vue";
export interface CartState { items: { id: string; price: number }[]; total: number }
export const cartKey: InjectionKey<DeepReadonly<CartState>> = Symbol("cart");
export const addItemKey: InjectionKey<(item: CartState["items"][number]) => void> = Symbol("addItem");

// Provider
const cart = reactive<CartState>({ items: [], total: 0 });
function addItem(item: CartState["items"][number]) {
  cart.items.push(item);
  cart.total += item.price;
}
provide(cartKey, readonly(cart));
provide(addItemKey, addItem);

// Any descendant
const cart = inject(cartKey);       // DeepReadonly<CartState> | undefined
const addItem = inject(addItemKey); // the only legal way to change it

🎮 Try it yourself

▶️ Open the interactive playground →

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

🧠 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

provide/inject hands descendants the live reactive object, not a copy — any component with the reference can mutate it, and Vue will propagate that write exactly as designed.
Vue's own guide already tells you the fix: keep mutations in the provider, and provide a function for anything a descendant is allowed to change. The gap is that most example code skips it.
readonly() (or shallowReadonly()) turns a silent, untraceable write into a dev-mode warning naming the exact key — wrap every provided value that descendants shouldn't mutate directly.
InjectionKey<T> replaces a magic string with a typed, typo-proof key and makes the "no provider above me" case a compile-time | undefined instead of a runtime surprise.
This isn't a Pinia replacement — it's the right shape for state scoped to one part of the tree; state read or written from outside that subtree belongs in a store instead.

That PromoBanner bug from the top is now impossible to write by accident: there's no writable cart to reach for, only an addItem call that shows up in a stack trace with your name on it. The next time inject() hands back an object, ask the one question this article is about: can whoever holds this write to it, and did you mean for them to?

What's the messiest provide/inject mutation bug you've chased down? Drop it in the comments — there's a good chance someone else is debugging the exact same shape right now.

📚 Read next

🚀 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___

I Deleted My Scroll-Lock Library's Ugly Hack. `scrollbar-gutter` Replaces It.

Parsa J — Mon, 02 Nov 2026 05:31:33 +0000

You open a modal. For one frame, before you can even read what it says, the page behind it flinches — the whole column of text shifts a few pixels to the right, like the browser flinched too.

Close the modal and it snaps back. Nobody styled that. Nobody asked for it. And if you build UI on Windows or Linux, you've shipped it to production without noticing, because on a Mac with the default trackpad scrollbars, it's nearly invisible. That's the part that makes this bug so sticky: the person who can see it and the person who has to fix it are usually not using the same operating system.

The fix everyone reaches for first

The standard explanation is that overflow: hidden on <body> — the thing every modal, drawer, and dropdown uses to stop the page scrolling behind it — also removes the vertical scrollbar. Removing the scrollbar hands its width back to the content. The content reflows into that space. The page shifts.

So people fix it the only way CSS used to allow: measure the scrollbar, then pay it back in padding.

function lockScroll() {
  const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
  document.body.style.paddingRight = `${scrollbarWidth}px`;
  document.body.style.overflow = "hidden";
}

function unlockScroll() {
  document.body.style.paddingRight = "";
  document.body.style.overflow = "";
}

This works. It's also the entire reason body-scroll-lock, react-remove-scroll, and half a dozen modal libraries ship their own copy of this exact measurement. Every one of them is solving the same problem: find out how wide the scrollbar would have been, then fake its presence with padding so nothing moves.

Before you keep reading — guess how many pixels of padding a 100-line copy-pasted "scroll lock" utility is usually off by, on the one OS nobody tested it on. The answer is almost always "enough to notice," because scrollbar width isn't a constant. It's roughly 17px on Windows across Chrome and Firefox alike, 0px on a Mac with overlay scrollbars — and the measurement has to run before you lock, every single time, or it reads the wrong number.

Why the shift happens at all

Here's the part the padding hack never actually fixes, it just hides: a classic scrollbar — the opaque kind with a visible track, standard on Windows and Linux — is laid out inside the element's content box. The browser treats it the same way it treats a sidebar: it eats width from whatever would otherwise render there. Turn the scrollbar off, and the content box grows back to full width. Turn it on, and the content box shrinks to make room. The content isn't "jumping" — it's being resized, every time, and resized fast enough that it reads as a flinch.

macOS's default overlay scrollbars don't do this. They float on top of the content without claiming any layout space, so toggling them on and off never changes anything's width. That's the whole reason this bug is invisible to a developer who only ever tests on their own Mac: the platform they build on structurally can't reproduce the thing their users are reporting.

The padding-right hack works around the resize by adding back exactly the width the scrollbar would have taken — but it only works if you already know the scrollbar is about to disappear, and you measured it correctly, before it does. It's compensating for a resize instead of preventing one.

`scrollbar-gutter: stable`: tell the layout to stop flinching

CSS has a property for exactly this now, and the name says what it does: reserve the scrollbar's gutter, stably, whether a scrollbar is currently needed or not.

html {
  scrollbar-gutter: stable;
}

Set this once, and the browser carves out the scrollbar's width in the layout permanently — for overflow: auto, scroll, and hidden. When your modal flips overflow to hidden to lock the page, the gutter is already reserved from before the modal ever opened. There's no width to give back, so there's nothing to resize, so there's nothing to flinch.

function lockScroll() {
  document.body.style.overflow = "hidden"; // that's it — no measuring, no padding
}

function unlockScroll() {
  document.body.style.overflow = "";
}

That's the whole fix for the layout-shift half of what a scroll-lock library does. You still need something to stop the page actually scrolling under a modal on touch devices — overflow: hidden alone doesn't catch every edge case there, and that part of a scroll-lock library can stay. But the width-measuring, padding-compensating dance that most of these libraries built their reputation on? scrollbar-gutter: stable makes it dead code.

There's a second value for layouts that center content and need symmetry on both sides:

html {
  scrollbar-gutter: stable both-edges;
}

both-edges mirrors the reserved gutter to the opposite inline edge, so if space is held open on the right, matching space opens on the left too — useful when a scrollbar appearing on only one side would visibly knock a centered layout off-center.

🎮 Try it yourself

▶️ Open the interactive playground →

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

The part that's easy to get wrong: overlay scrollbars opt out of this too

Here's the honest asterisk, and it's the same one from earlier in reverse: scrollbar-gutter: stable only reserves space for classic scrollbars. MDN says it plainly — "When using overlay scrollbars, the gutter will not be present." On a system with overlay scrollbars, setting this property changes nothing, because there was never any layout space being given up in the first place.

That means you can't fully verify this fix by eyeballing your own Mac. You need a Windows or Linux machine, a Windows/Linux VM, or Chrome DevTools' device toolbar won't help either — it emulates viewport size, not the host OS's scrollbar rendering mode. The honest test is someone, or something, running an actual classic-scrollbar environment.

Is this safe to ship today?

Yes, with one small caveat worth knowing rather than discovering. Chrome and Edge have supported scrollbar-gutter since version 94 (2021), and Firefox since version 97 (2022) — this has quietly worked for most of your users for years. Safari was the holdout; it landed support in Safari 18.2, released in December 2024, which is also what pushed scrollbar-gutter to Baseline "newly available" that same month. If you need to support Safari versions older than 18.2, the property is simply ignored there — no error, no warning, the page just behaves exactly like it always did. That's a safe degrade, not a broken one, so there's no reason to gate this behind a feature query unless you want to show a different UI specifically for browsers that lack it.

The next time a modal makes your page twitch, you'll know exactly why — and now you know the one-line reason to stop paying JavaScript to measure a number CSS can just reserve for you.

Still carrying a scroll-lock library in your bundle for this exact problem? Go check what it actually does under the hood — there's a decent chance half of it just became unnecessary.

🧠 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.

📚 Read next

🚀 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 Activity Component: The State Between Render and Remount

Parsa J — Sun, 01 Nov 2026 18:40:36 +0000

You hide a settings panel with {isOpen && <Panel />}. The user reopens it two seconds later, and the unsaved toggle they'd flipped is back to its default. The scroll position is gone. The debounced search they'd typed into a nested filter has vanished. Nothing is broken — React unmounted <Panel /> and mounted a brand new one, exactly as that code tells it to. You just didn't mean to ask for that.

Before React 19.2, there was no built-in way to say "hide this, but keep it exactly as it was." CSS (display: none while the component stays mounted) keeps the state, but its effects keep running in the background — timers ticking, subscriptions open, polling a screen nobody can see. Unmounting runs cleanup correctly but throws the state away. There was no option between "alive and visible" and "gone."

React 19.2 (released October 2025) added <Activity> to close that gap: a built-in way to hide a subtree while keeping its state intact. React 19.3 — released September 2026 and patched to the current npm latest, 19.3.1, in October — shipped several bug fixes for it, including one around useSyncExternalStore updates while hidden, that are worth understanding on their own, because they show exactly where the "hidden but alive" model gets subtle. This is episode eight of React Deep Dive, and it picks up where episode one, on re-render vs. remount, left off: <Activity> is neither of those two things. It's a third state, with its own rules, and treating it like either of the other two is exactly how the 19.3 bugs happened.

What you'll learn

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

Explain precisely what <Activity mode="hidden"> preserves and what it tears down — state, effects, refs, and renders are four separate questions, not one
Replace a {condition && <Panel/>} pattern with <Activity> when hiding, not destroying, is what you actually want
Predict when a hidden subtree still re-renders (and why that's not a bug)
Avoid the two traps that the 19.3 patch notes had to fix for the React team itself
Use <StrictMode> to catch the effect-cleanup bugs that <Activity> surfaces

Who this is for

You're comfortable with function components, useState, and useEffect, and you've been bitten at least once by state resetting when you only meant to hide something. You don't need to have used <Activity> before.

The problem: hiding isn't unmounting, and unmounting isn't hiding
The mental model
The walkthrough
Edge cases and gotchas
Best practices
FAQ
Cheat sheet
Key takeaways

The problem: hiding isn't unmounting, and unmounting isn't hiding

Say you're building a dashboard with three report tabs. Each tab has its own view: a filter form, a live-updating counter from a useEffect-driven interval (think "records processed," polled every second), and a draft note the user is typing. Switch tabs, and here's the naive version:

function Dashboard({ activeTab }) {
  return (
    <>
      {activeTab === "sales" && <ReportPanel label="Sales" />}
      {activeTab === "ops" && <ReportPanel label="Ops" />}
      {activeTab === "support" && <ReportPanel label="Support" />}
    </>
  );
}

This works, in the sense that it compiles and nothing throws. But switch from "Sales" to "Ops" and back, and the Sales ReportPanel is a completely new instance. Its counter restarts at zero. Its draft note is empty. Its useEffect cleanup ran when you left, and a fresh mount effect ran when you came back — including any expensive setup it does on mount. You wanted a tab switch; React gave you a demolition and a rebuild.

The instinctive fix is to keep everything mounted and hide the inactive panels with CSS:

function Dashboard({ activeTab }) {
  return (
    <>
      <div style={{ display: activeTab === "sales" ? "block" : "none" }}>
        <ReportPanel label="Sales" />
      </div>
      <div style={{ display: activeTab === "ops" ? "block" : "none" }}>
        <ReportPanel label="Ops" />
      </div>
      <div style={{ display: activeTab === "support" ? "block" : "none" }}>
        <ReportPanel label="Support" />
      </div>
    </>
  );
}

This keeps the state, but now you've traded one bug for another: the Sales panel's interval keeps polling, its effects keep subscribing, and its hidden DOM keeps costing you layout and memory for every tab the user isn't looking at. You've solved the state problem by un-solving the cleanup problem.

<Activity> is React's answer to "I want both": state survives, but effects still tear down and rebuild the way they would for a component you actually cared about keeping correct.

The mental model

The mental model: Render, remount, and <Activity mode="hidden"> are three different operations, and they disagree on three separate things — state, effects, and rendering — not just one axis you can call "aliveness."

	Stays mounted (same instance)	`<Activity mode="hidden">`	Unmount (remove from the tree)
State (`useState`, `useReducer`)	Preserved	Preserved	Destroyed
Effects (`useEffect`)	Keep running	Torn down on hide, re-created on show	Torn down, never re-created (new instance builds fresh ones)
Rendering on prop/context change	Happens normally	Still happens, at lower priority	Doesn't happen — there's nothing there
DOM	Visible	Hidden (`display: none`), node kept	Removed
Refs	Point at the live node	Still point at the (now hidden) node	Become `null`

Read the middle column again: hidden is not the same as paused, and it is not the same as destroyed. A component inside a hidden <Activity> keeps its state, loses its effects, and — this is the part people get wrong — keeps rendering when something above it changes, just at a priority React considers less urgent than whatever's actually on screen. That last row is the one the 19.3 patch notes had to fix bugs around, because it's the one that breaks the intuition "hidden means nothing happens here."

Here's the shape in code, next to the two things it's between:

import { Activity, useState } from "react";

function Dashboard({ activeTab }) {
  return (
    <>
      <Activity mode={activeTab === "sales" ? "visible" : "hidden"}>
        <ReportPanel label="Sales" />
      </Activity>
      <Activity mode={activeTab === "ops" ? "visible" : "hidden"}>
        <ReportPanel label="Ops" />
      </Activity>
      <Activity mode={activeTab === "support" ? "visible" : "hidden"}>
        <ReportPanel label="Support" />
      </Activity>
    </>
  );
}

Switch tabs now, and the inactive ReportPanels stay mounted as far as state is concerned (the draft note survives), but their effects clean up (the polling interval stops) the moment they go hidden, and start fresh again the moment they're shown. No wasted polling, no lost draft.

Historical aside, labelled: before 19.2 stabilized this, an experimental build exposed the same idea as unstable_Activity. If you see import { unstable_Activity as Activity } from "react" in an older blog post or a pinned pre-19.2 dependency, that's the pre-stable name — don't write it in new code. The stable export is just Activity, no prefix.

The walkthrough

Step 1 — the smallest correct example

import { Activity, useState } from "react";

function Sidebar({ isOpen }) {
  const [filter, setFilter] = useState("");

  return (
    <Activity mode={isOpen ? "visible" : "hidden"}>
      <input value={filter} onChange={(e) => setFilter(e.target.value)} />
    </Activity>
  );
}

Key concept: mode is the entire API surface for visibility — "visible" or "hidden" (it defaults to "visible" if you omit it). There's no mode="unmounted"; if you want a true unmount, don't render the <Activity> at all. <Activity> only ever answers "show or hide," never "destroy."

Step 2 — proving the effect actually tears down

function ReportPanel({ label }) {
  const [count, setCount] = useState(0);
  const [draft, setDraft] = useState("");

  useEffect(() => {
    const id = setInterval(() => setCount((c) => c + 1), 1000);
    return () => clearInterval(id); // runs when Activity hides this subtree
  }, []);

  return (
    <div>
      <h3>{label}: {count}</h3>
      <textarea value={draft} onChange={(e) => setDraft(e.target.value)} />
    </div>
  );
}

Hide this panel's <Activity> and the interval's cleanup runs immediately — count stops climbing. Show it again, and the effect's setup function runs again, starting a new interval. count and draft were never touched by any of this; they're still sitting in React's fiber for this component, exactly where you left them. The playground below is this exact component, running the real reconciler, so you can watch the counter freeze and the draft survive in real time.

Step 3 — the row people miss: hidden subtrees still render

This is the one the mental model table flags and most tutorials skip. A hidden <Activity> doesn't freeze its children — it keeps re-rendering them when their props or context change, just scheduled at a lower priority than the visible UI. Why would React bother? Two real reasons, both from the official docs:

Pre-rendering. A <Activity mode="hidden"> on initial render still renders its children (without mounting their effects), which lets data-fetching components start loading before the user ever opens that tab — so when they do, it's instant instead of a fresh Suspense fallback.
Keeping derived UI correct. If a hidden panel's rendered output depends on a prop from its parent (say, a shared "last synced at" timestamp), it should show the right value the instant it's revealed, not a stale one from the moment it was hidden.

The playground's "Bump shared prop" button demonstrates this directly: it changes a value passed into every ReportPanel, visible or hidden, and the hidden panel's render count still climbs — while its effect-mount count does not. Those two counters moving independently is the mental model, observed instead of described.

Step 4 — what the 19.3 bug fixes actually tell you

React 19.3's changelog lists several <Activity> fixes: issues with useSyncExternalStore updates while hidden, portal visibility, metadata hoisting, and error handling. The pattern across them is instructive: every one is a place where "still rendering, but hidden, with effects torn down" created a seam that a feature built on a simpler always-mounted/never-mounted assumption fell through. useSyncExternalStore subscribes to an external store through an effect-like mechanism — exactly what <Activity> tears down on hide — so an update arriving while hidden needs special handling to avoid being silently lost or double-applied on reveal. If you subscribe to anything external (WebSockets, browser APIs, a state manager outside React) inside a component that might live under an <Activity>, assume the subscription is gone while hidden and gets rebuilt from current state when shown.

Edge cases and gotchas

Text-only children render nothing when hidden. Hiding works by applying display: "none" to a wrapper — bare text has no element to attach that to, so it just doesn't render. Wrap bare text in an element if it might end up inside an <Activity>.
Side effects outside useEffect keep running. A <video>, <audio>, or <iframe> isn't paused by hiding — its DOM node is still alive, still doing whatever it was doing. Pause it explicitly, in a useLayoutEffect cleanup tied to the visual hide.
Refs still point at hidden DOM. Unmounting nulls a ref; hiding doesn't — the node still exists, just invisible. Code that treats "ref is set" as "user can see it" will be wrong.
StrictMode is how you catch the bugs this exposes. Effects now mount and unmount far more often than a typical lifetime suggests — every hide/show cycle, not just mount/unmount. Any effect that assumed its cleanup never really had to undo everything gets exposed fast. Develop with <StrictMode> so this surfaces before production does.
Interaction with <ViewTransition>. If an <Activity> reveal happens inside startTransition, and the tree uses <ViewTransition> (also stable in 19.3), showing it triggers that boundary's enter animation and hiding triggers exit — the two features compose by design.

Best practices

Reach for <Activity> when state is expensive to rebuild and the hide is temporary — tabs, a collapsible sidebar, a wizard step, a modal reopened with the same draft. The signal: the user will plausibly come back to this exact state.
Don't make it a default replacement for conditional rendering. If the user is done with something for good (a dismissed notification, a finished onboarding step), unmounting is correct and cheaper — nothing left to render at low priority, nothing to reconcile later.
Don't treat it as a pause button for real-world side effects (payments in flight, a write to a server). Hiding a subtree doesn't cancel an in-flight promise; it only affects effect lifecycle and state.
If a hidden subtree subscribes to anything external, write its effect assuming the subscription is gone while hidden — resync from current state on the next mount rather than assuming buffered delivery.
Keep mode a useState/prop-driven value, not something you mutate imperatively — <Activity> reacts to re-renders like anything else in React.

FAQ

Is `<Activity>` the same thing as `display: none`?

No. It uses display: none for the visual hiding, but that's one of four things it does — it also tears down effects (plain CSS never does), preserves state across the hide (an unmount never does), and keeps rendering hidden children at lower priority (a component you've stopped rendering can't do at all).

Does `<Activity>` replace `key`-based remounting?

No — opposite problems. key forces React to treat something as a new instance, which is right when you want fresh state. <Activity> keeps the same instance alive while hidden. Want a reset? Use key. Want to preserve exactly what's there? Use <Activity>.

Will `<Activity>` fetch data for a hidden tab before the user opens it?

Under specific conditions: if the hidden children read data through something Suspense-activating — a promise read with use() — a hidden <Activity> can pre-render and start that fetch early. Data fetched inside a useEffect is not: effects don't run while hidden, so effect-based fetching only starts once the subtree becomes visible.

Does hiding with `<Activity>` cost anything if I never show the content again?

Some — the hidden subtree still occupies a spot in the fiber tree and can still re-render at low priority. For content the user is realistically done with, unmount it; reach for <Activity> specifically because you expect a return visit.

Can I nest `<Activity>` components?

Yes — visibility composes as expected. A visible <Activity> inside a hidden one is still effectively hidden, because its ancestor is hidden.

Cheat sheet

import { Activity, useState, useEffect } from "react";

// 1. Import — stable since React 19.2, no prefix.
// import { unstable_Activity as Activity } from "react"; // ❌ pre-19.2 only

// 2. Usage — mode is the whole API.
<Activity mode={isVisible ? "visible" : "hidden"}>
  <ExpensiveSubtree />
</Activity>

// 3. What survives hiding vs. what doesn't:
//    state (useState/useReducer)         → preserved
//    effects (useEffect)                 → torn down on hide, re-created on show
//    rendering on prop/context change    → still happens, lower priority
//    DOM node                            → kept, display: none
//    refs                                → still point at the (hidden) node

// 4. Pick the right tool:
//    "destroy it for good"        → don't render it (plain conditional)
//    "reset it on purpose"        → key={newId}
//    "hide it, keep it alive"     → <Activity mode="hidden">

// 5. Gotchas:
//    - bare text child while hidden renders nothing (no element to hide)
//    - <video>/<audio>/<iframe> keep running while hidden — pause explicitly
//      in a useLayoutEffect cleanup if that matters
//    - external subscriptions (useSyncExternalStore, sockets) are torn down
//      on hide — resync on remount, don't assume buffered delivery
//    - develop with <StrictMode> to catch effects that assumed they'd only
//      ever run once

Key takeaways

<Activity mode="hidden"> is a third state, not a point on the line between "mounted" and "unmounted": state is preserved, effects are torn down and rebuilt, and rendering on prop change still happens — just at lower priority.
It solves the specific problem of keeping expensive-to-rebuild state alive across a hide/show cycle without paying the cost of a fully-live, always-rendering component.
The 19.3 bug fixes for useSyncExternalStore, portals, and metadata under <Activity> all trace back to the same seam: features built assuming "mounted" or "unmounted" as the only two states had to be taught about the third one.
Reach for it when the user will plausibly come back; reach for key when you want a clean reset; reach for plain conditional rendering when the content is genuinely done.

That chat-draft bug from episode one and the dashboard tab bug here are mirror images of each other — one was an accidental remount nobody wanted, this one is an accidental unmount nobody wanted. Same underlying lesson both times: React only does what your JSX actually asks for, never what you meant. Have you reached for <Activity> yet, or are you still hiding things with CSS and hoping the effects behave? Tell me what you're using it for in the comments.

🎮 Try it yourself

▶️ Open the interactive playground →

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

🧠 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.

📚 Read next

🚀 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 Hardcoding Color Variants. Relative Color Syntax Does It.

Parsa J — Sun, 01 Nov 2026 12:57:09 +0000

The PR comment was two words: "wrong blue." Not a bug report, not a reproduction — a designer scrolling through a staging build, stopping on the "Upgrade" button's hover state, and flagging it because something about it felt off against the rest of the rebrand that had shipped two weeks earlier.

They were right, and it took longer than it should have to find out why. The button's resting color matched the new brand blue exactly — that token had been updated the day the rebrand landed. Its hover color was still the old brand blue, darkened. Nobody had touched it, because nobody remembered it existed.

Five variables, one of which actually gets updated

Open almost any design system's color file and you'll find the same shape: one brand color, and a handful of hand-picked variants sitting next to it that all look derived but are actually just... more hex codes.

:root {
  --brand: #3b6fd6;
  --brand-hover: #2f58ab;      /* "a bit darker" — picked by eye, once */
  --brand-active: #244289;     /* "darker still" — same deal */
  --brand-border: #6e92e1;     /* "a bit lighter" */
  --brand-tint: rgba(59, 111, 214, 0.08); /* "faint background wash" */
}

Every one of those four extra values is somebody's good-faith attempt, at some point in the past, to eyeball a lighter or darker or more-transparent version of --brand. They're not wrong on day one. The problem shows up the day --brand changes and the other four don't — because CSS has no idea they were ever related. To the engine, --brand-hover isn't "darker --brand." It's just a string that starts with #2f58ab, full stop.

The "obvious" fix is discipline: a comment reminding whoever edits --brand to also update the other four, or a design-tokens build step that regenerates them from a single source before CSS ever sees them. Both work, right up until the person making a one-line brand tweak six months from now doesn't know the build step exists, or skims past the comment. Discipline that depends on nobody being in a hurry isn't a fix — it's a bet, and the rebrand PR is the bet losing.

The variables were never the problem — storing the relationship was

Here's the reframe that matters: --brand-hover was never really an independent color. It was always a function of --brand — "darker, same hue." --brand-tint was always "the same color, 8% opaque." The relationship was real and well understood by whoever first picked those hex codes. What got lost was that the relationship lived in a person's head for thirty seconds and then evaporated, leaving only its one-time output behind, frozen in a stylesheet forever.

What you actually want is for CSS to store the relationship, not just a snapshot of what it once produced — and that's a genuinely new category of thing for CSS to express. For most of CSS's life, a color value was a dead end: #3b6fd6 tells the renderer what to paint, but nothing about where it came from or how to get a cousin of it. color-mix() loosened that slightly — you can blend two colors — but blending two colors isn't the shape of this problem. You don't have two brand colors to mix; you have one color, and you want its lightness turned down a notch while everything else about it stays put.

Before you keep reading: what would you even call the CSS feature that lets you say "same color, just darker"? It's a fair question, because until relatively recently there wasn't a clean answer.

Relative color syntax: read a color's own channels back out

Relative color syntax lets a color function take another color as input and expose that color's own channels as variables you can do math on, right there in the function call:

:root {
  --brand: #3b6fd6;

  /* "same hue and chroma as --brand, just darker" */
  --brand-hover:  oklch(from var(--brand) calc(l - 0.12) c h);
  --brand-active: oklch(from var(--brand) calc(l - 0.20) c h);

  /* "same color, lighter, for a border" */
  --brand-border: oklch(from var(--brand) calc(l + 0.15) c h);

  /* "same color, 8% opaque" */
  --brand-tint: oklch(from var(--brand) l c h / 8%);
}

Read the oklch(from var(--brand) ...) part literally: "take --brand, convert it to OKLCH, and give me three variables back — l for lightness, c for chroma, h for hue." Whatever you write after that is just CSS math on those three numbers (plus an optional alpha after the slash). calc(l - 0.12) means "this color's own lightness, minus 0.12" — not a hardcoded lightness value, a relationship to whatever --brand happens to be right now.

Change --brand to a rebrand's new blue, or swap it entirely for a dark-mode theme, and every line below it recomputes. There's no second hex code to forget, because there is no second hex code — --brand-hover isn't stored anywhere; it's derived, every time the browser needs it, from the one variable a human actually edits.

This isn't OKLCH-only, either. rgb(), hsl(), and color() all support the same from syntax, exposing whichever channels that color space naturally has:

/* rgb()'s own channels: r, g, b (0–255), alpha */
.badge { background: rgb(from var(--brand) r g b / 15%); }

/* hsl()'s own channels: h, s, l, alpha — s and l come back as plain
   numbers (0-100), not percentages, so the math below uses 10, not 10% */
.link:hover { color: hsl(from var(--brand) h s calc(l - 10)); }

OKLCH is usually the better pick for lightness math specifically, because it's designed so that "lightness" tracks perceived brightness consistently across hues — nudging l down by the same amount darkens a yellow and a blue by roughly the same perceived amount. Nudge hsl()'s l channel the same way and the result can feel inconsistent hue to hue, because HSL's lightness was never built to model human perception in the first place.

🎮 Try it yourself

▶️ Open the interactive playground →

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

The one sharp edge: clamp your math

calc(l - 0.12) is honest math, which means it'll happily produce a number outside the range that makes sense. Pick a brand color that's already quite dark, subtract 0.20 from its lightness, and l can go negative — which isn't a color error so much as a "this doesn't mean anything" result, rendered as whatever the browser decides black looks like.

The fix is the same clamp() you'd reach for anywhere else in CSS, wrapped around the channel math:

--brand-hover: oklch(from var(--brand) clamp(0, calc(l - 0.12), 1) c h);

That one change makes the derivation safe for any input color, including ones your design system doesn't control yet — a user-customizable accent color, say, or a brand color read from a CMS. Skip the clamp and the formula only works for colors in roughly the lightness range you tested it against, which defeats a good chunk of the point: a derivation that only works for some inputs is just a more elaborate hardcoded value.

Is this safe to ship, or is it another flag-gated preview?

Safe to ship — but the rollout order isn't what you'd guess. Safari 16.4 (March 2023) was the earliest browser with something, but it was a partial pass at an older draft of the spec with real parsing bugs; that implementation was later replaced, not extended. Chrome and Firefox did the work of actually matching the final spec through 2024 (Firefox in Firefox 128, July 2024), and Safari didn't catch up — bug fixes included — until Safari 18 in September 2024. So for the exact forms used above, Safari was last to ship the behavior this post describes, not first. Either way, that was over two years ago: by now every major evergreen browser has unprefixed, unflagged, spec-correct support, and there's no realistic "but what about X" objection left to raise for a typical modern browser matrix. If your project still has to support browsers from before that window, the fallback is simple and honest: keep writing literal hex variants for those browsers, and layer the relative syntax on top for everyone else — it degrades to "the hardcoded value you already had," not to a broken page.

🧠 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.

The bug wasn't really "someone forgot to update a hex code." It was that the stylesheet never had anywhere to put the fact that --brand-hover meant "darker --brand" — so that knowledge lived in a person's memory instead, with exactly the shelf life you'd expect. Relative color syntax isn't a shorter way to write the same five hex codes. It's a way to stop writing four of them at all.

Where does your own color system still keep that kind of relationship in a comment instead of in the CSS itself?

📚 Read next

🚀 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 J

Stop Shipping Search Boxes With a Race Condition

The fix that made it rarer, not gone

The response you render isn't the one you think it is

The fix: stop trusting arrival order, track identity instead

🎮 Try it yourself

It's not just search boxes

Guard the identity, not the order

🧠 Test yourself

You're Blocking Scroll by Default. `passive: true` Fixes It.

The fix that didn't fix it

Why a touchmove listener can freeze a scroll that never gets cancelled

🎮 Try it yourself

The one-line fix

"Isn't this already the default?"

The list, scrolling again

🧠 Test yourself

📚 Read next

NestJS 12.2: Why validationError.target Is Now undefined

What you'll learn

Who this is for

Table of contents

The problem: an exceptionFactory that used to work

The mental model: target, value, and property are three different things

Stage 1: why 12.2 changed the default

Stage 2: fixing the broken exceptionFactory

Stage 3: restoring the old behavior on purpose

Stage 4: the quieter 12.2 changes riding along

Edge cases and gotchas

Best practices

FAQ

Does this break validation itself, or just error reporting?

Will my app silently stop validating anything after this upgrade?

Does error.value ever get suppressed the same way?

Is this in the official migration guide, or just the release notes?

Can I set validationError.target per route instead of globally?

Cheat sheet

Key takeaways

Ending

🎮 Try it yourself

🧠 Test yourself

📚 Read next

Stop Hacking Base64 With btoa(). toBase64() Fixes It Natively.

The code that worked right up until it didn't

It gets worse with text, not just files

Why both bugs have the same root cause

🎮 Try it yourself

The fix: encode the bytes directly

The option you'll actually reach for: URL-safe tokens

The part worth being honest about

The report export, fixed

🧠 Test yourself

Running the meeting is a different job than being in one

It's not the same skill as talking in one

The second audience nobody mentioned

So what do you actually say?

Where this goes wrong

The part that isn't about skill

Monday

📚 Read next

getCurrentPosition() Has No Default Timeout. That's the Trap.

The code that looks fully handled

The default timeout is not "some reasonable number." It's Infinity.

The other default nobody reads: maximumAge: 0

watchPosition() has the same shape of bug as a forgotten clearInterval

It's not a Promise, and that's the last gotcha

The one real constraint: it needs a secure origin

🎮 Try it yourself

🧠 Test yourself

📚 Read next

Your Canvas Is Freezing the Page. OffscreenCanvas Fixes That.

The fix everyone reaches for first

The part that's easy to miss: drawing itself blocks the page

The fix: move the context itself into the worker

Why the page stays responsive now

🎮 Try it yourself

When the main thread was fine all along

Is this safe to ship today?

🧠 Test yourself

📚 Read next

Why a `touchmove` listener can freeze a scroll that never gets cancelled

Does `error.value` ever get suppressed the same way?

Can I set `validationError.target` per route instead of globally?

The default timeout is not "some reasonable number." It's `Infinity`.

The other default nobody reads: `maximumAge: 0`

`watchPosition()` has the same shape of bug as a forgotten `clearInterval`

What `'navigation'` actually validates

`ensureStatic` vs `instant`

`scrollbar-gutter: stable`: tell the layout to stop flinching

Is `<Activity>` the same thing as `display: none`?

Does `<Activity>` replace `key`-based remounting?

Will `<Activity>` fetch data for a hidden tab before the user opens it?

Does hiding with `<Activity>` cost anything if I never show the content again?

Can I nest `<Activity>` components?