DEV Community: Parsa Jiravand

getCurrentPosition() Doesn't Just Check — It Prompts

Parsa Jiravand — Sat, 26 Sep 2026 12:26:10 +0000

You're building a "find stores near you" banner. The right move, UX-wise, is to explain why you want the visitor's location before the browser's blunt little system dialog interrupts them — but only if that dialog hasn't already fired. If they already said yes, just get the location and skip the banner. If they already said no, don't ask again; show a manual city picker instead.

So before you render anything, you write a quick check: has this visitor already decided?

navigator.geolocation.getCurrentPosition(
  () => showStoresNearMe(),
  (err) => {
    if (err.code === err.PERMISSION_DENIED) showManualPicker();
  }
);

You test it in a fresh incognito window. The system permission dialog pops up immediately — the exact one you were trying to gate behind your own friendly copy. Not after your banner. Instead of it.

Guess before you scroll: the code above isn't buggy. It's doing exactly what getCurrentPosition is supposed to do. The bug is in the assumption that calling it was a way to check something.

There's no "just checking" with the Geolocation API

getCurrentPosition doesn't have a peek mode. Every call is a real request for the visitor's location, and the browser treats it that way: if the permission state for this origin is still undecided, it shows the system prompt right then, synchronously with your call. If the visitor already granted permission, it skips straight to fetching a position. If they already denied it, your error callback fires with PERMISSION_DENIED — no dialog, but you only find that out after asking.

That last case is the closest thing to a "check" the API gives you, and it's a bad one: to learn the state, you have to make the same call you'd make to actually use the feature, and if the state happens to be "undecided," making that call is deciding it — badly, with zero context, at a moment you didn't choose.

There's a reason this feels like a design gap and not a skill issue: the thing you actually want to read — "has this origin already been asked, and what did the visitor say?" — isn't geolocation-specific data at all. It's account-keeping the browser does for every permission-gated feature, and the Geolocation API was never built to expose it. You were reaching for a getter through a function whose entire job is to act.

The API that only reads

The Permissions API is that getter. navigator.permissions.query() asks the browser "what's the current state of this permission for this origin?" and resolves with the answer — without ever triggering the system dialog itself, regardless of what the answer turns out to be:

const status = await navigator.permissions.query({ name: "geolocation" });

console.log(status.state); // "granted" | "denied" | "prompt"

if (status.state === "granted") {
  showStoresNearMe(); // safe to call getCurrentPosition silently
} else if (status.state === "prompt") {
  showWhyWeAskBanner(); // explain first, THEN call getCurrentPosition
} else {
  showManualPicker(); // already denied — don't ask again
}

prompt means "undecided" — the browser hasn't shown this visitor a dialog for this permission on this origin yet. That's your one and only safe moment to show your own explanation first. Miss it — by calling the real API to "check" — and the browser's dialog wins the moment instead of yours.

The status object isn't a one-shot snapshot, either. It's a live handle you can subscribe to:

status.addEventListener("change", () => {
  console.log("permission is now:", status.state);
});

If the visitor opens your site's permission settings via the browser's UI (the little padlock icon) and flips geolocation while your tab is still open, change fires and status.state updates — no reload, no re-query. That's useful for exactly the kind of banner you're building: if someone denies it mid-session, you can swap the banner for the manual picker on the spot instead of waiting for their next visit.

The catch: not every browser recognizes every name

The Permissions API supports more than geolocation — notifications, camera, microphone, persistent-storage, clipboard-read, and others, each queried by its string name. But which names a given browser recognizes varies, and MDN is explicit about what happens when you ask for one it doesn't: the promise doesn't resolve to some "unknown" state — it rejects with a TypeError.

try {
  const status = await navigator.permissions.query({ name: "camera" });
  console.log(status.state);
} catch (err) {
  // Some browsers don't recognize "camera" as a queryable name.
  // Fall back to your default UX rather than assuming a state.
  console.log("couldn't read that permission here:", err.message);
}

Skip the try/catch and an unsupported name doesn't quietly do nothing — it throws an unhandled rejection in the middle of your permission logic. Given how much this varies by browser and by permission name, treat every query() call as something that can fail, not just something that can resolve to three states.

The lesson

"Check first, then ask" is good instinct. The mistake is reaching for the feature's own API to do the checking — getCurrentPosition, Notification.requestPermission, navigator.mediaDevices.getUserMedia — when each of those is built to act, and for a permission still in prompt state, acting and asking are the same button. The Permissions API is the one part of the platform whose entire job is to answer without acting. If you find yourself calling a feature just to see what it does before deciding whether to really call it, that's the tell: you wanted a read, and you reached for a write.

Numbers and prose only get you so far here — the difference between "reading" and "doing" is more convincing when you can trigger both yourself and watch which one leaves a system dialog behind.

🎮 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 7-question quiz →

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

Go check the permission-gated features already in your app — location, notifications, the clipboard, the camera. If any of them decide whether to show your own explanation by calling the real API first, that's a prompt firing at a moment you didn't pick. What's the worst time your app's permission prompt has ever popped up on someone?

🚀 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 Guards: CanActivate, ExecutionContext & Reflector

Parsa Jiravand — Sat, 26 Sep 2026 12:25:38 +0000

A code review flags a "protected" admin endpoint. The controller has @UseGuards(RolesGuard) on the class, RolesGuard injects a UserService to check role hierarchy, and it's registered application-wide with app.useGlobalGuards(new RolesGuard(reflector, userService)) in main.ts. It looks careful. It is also broken: userService is undefined inside the guard, on every single request, and no test would have caught it because the app never crashed — it just let every request through the branch that assumes a user has no elevated role.

Nothing here is a typo. The guard class is correct. The decorator is correct. The one thing wrong is how the guard was registered — and until you know what a guard actually is to Nest's container, that line looks completely reasonable.

This is written against NestJS 12.0.x (verified September 2026, current @nestjs/core release, v12.0.4). The CanActivate interface, ExecutionContext, and Reflector covered here have been stable since well before v9 and are untouched by v12's ESM and Standard Schema changes — nothing in this article is version-fragile.

What you'll learn

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

Explain what a guard actually is — a DI-instantiated class, not a function you happen to call canActivate
Read and use ExecutionContext to get at the request, the handler, and the controller class from inside a guard
Build a Reflector-backed @Roles() decorator and understand exactly why the method's metadata overrides the class's
Register a global guard the right way (APP_GUARD) so it keeps its dependency injection
Predict, for any combination of global/controller/method guards, the exact order they run in and what "all must pass" means

Who this is for

You've written a NestJS controller, used @UseGuards() at least once, and you know what @Injectable() does. If you haven't read the NestJS request lifecycle episode of this series, it's a useful map of where guards sit relative to middleware, interceptors, and pipes — but this article is self-contained.

The problem: a guard that quietly can't do its job
The mental model: a guard is a provider, not a function
Stage 1: the smallest correct guard
Stage 2: ExecutionContext, properly
Stage 3: Reflector and a real @Roles() decorator
Stage 4: registering a global guard without losing DI
Stage 5: composing guards — order and "all must pass"
Edge cases and gotchas
Best practices
FAQ
Cheat sheet
Key takeaways

The problem: a guard that quietly can't do its job

Here's the guard from the intro, in full:

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(
    private reflector: Reflector,
    private userService: UserService, // meant to check role hierarchy
  ) {}

  canActivate(context: ExecutionContext): boolean {
    const required = this.reflector.get<string[]>("roles", context.getHandler());
    if (!required) return true;
    const { user } = context.switchToHttp().getRequest();
    // userService is undefined here — this branch always throws or always no-ops
    return this.userService.hasAnyRole(user, required);
  }
}

And here's how it was wired up, because "global" sounded like the right word for "runs on every route":

// main.ts — looks reasonable, is quietly broken
const app = await NestFactory.create(AppModule);
app.useGlobalGuards(new RolesGuard(new Reflector(), /* userService? */ undefined));

app.useGlobalGuards() takes an instance. Nothing about that instance goes through Nest's dependency injection — you constructed it yourself, with new, outside any module, before the application's providers even exist to hand it a real UserService. Nest will happily call canActivate() on this object for every request. It just can't give it the dependency the guard was written to use.

The fix isn't a different guard. It's a different registration, covered in Stage 4. But to see why that fix works, you need the actual mental model of what a guard is.

The mental model: a guard is a provider, not a function

The mental model: a NestJS guard is an ordinary DI provider — the same kind of class as a service — that additionally implements one method, canActivate(context: ExecutionContext), which Nest calls immediately before it would otherwise invoke your route handler. If canActivate resolves to true, the request keeps moving toward interceptors, pipes, and the handler. If it resolves to false, or throws, the handler never runs and Nest hands the request straight to the exception-filter layer.

Three consequences fall out of that one sentence, and they're the three things the intro's bug got wrong:

A guard only gets real dependency injection if Nest constructs it. @UseGuards(RolesGuard) (passing the class) lets Nest instantiate it through the container, resolving its constructor arguments normally. new RolesGuard(...) (passing an instance you built) does not — you're on your own for every dependency.
A guard doesn't see "a request" in the abstract — it sees an ExecutionContext. That's a wrapper Nest builds fresh for every incoming call, giving the guard a uniform way to reach the underlying request and to ask "what handler and class is Nest about to invoke?" — which is exactly what a guard needs to look up route-specific metadata.
A guard's decision is binary, not additive. It either lets a request through or it doesn't. Anything more nuanced than "yes/no" — attaching data, transforming the body — is an interceptor's or a pipe's job, not a guard's.

Stage 1: the smallest correct guard

The simplest guard that compiles and does something real:

import { CanActivate, ExecutionContext, Injectable } from "@nestjs/common";

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    return Boolean(request.headers.authorization);
  }
}

Apply it to one route:

@UseGuards(AuthGuard)
@Get("profile")
getProfile(@Req() req: Request) {
  return req.user;
}

Key concept: canActivate can return boolean, Promise<boolean>, or Observable<boolean> — Nest awaits or subscribes to whichever you give it. A guard that calls a database or an external identity provider to check a session is completely normal; just make it async canActivate(...): Promise<boolean> and Nest will wait for it before deciding.

Stage 2: ExecutionContext, properly

ExecutionContext is the single argument every guard, interceptor, and exception filter receives, and it answers two different questions:

"What kind of call is this, and what's the underlying request object?" — via switchToHttp(), switchToRpc(), or switchToWs(). Most guards only ever call context.switchToHttp().getRequest(), but the same guard class can run in front of a WebSocket gateway or a microservice handler if you check context.getType() first and branch — that's what makes ExecutionContext a context, not just an HTTP request wrapper.

"Which handler and which class is Nest about to call?" — via context.getHandler() (the specific route method, as a function reference) and context.getClass() (the controller class). This half is what makes metadata-driven guards possible, because it's the only way a guard can ask "does this specific route carry a @Roles(...) decorator?" — the guard runs once per registration, but getHandler()/getClass() tell it which route it's currently deciding for.

canActivate(context: ExecutionContext): boolean {
  const handlerName = context.getHandler().name;      // e.g. "getProfile"
  const controllerName = context.getClass().name;     // e.g. "UsersController"
  const request = context.switchToHttp().getRequest();
  // ...
}

Key concept: getHandler() and getClass() return the raw function/class references, not strings — they exist so you can hand them to Reflector, which looks up metadata attached to those exact references. That's the bridge to Stage 3.

Stage 3: Reflector and a real `@Roles()` decorator

Hardcoding a role check per route doesn't scale, and neither does branching on handler.name — a rename breaks it silently. The idiomatic pattern is a custom decorator that attaches metadata, and a Reflector that reads it back inside a guard.

// roles.decorator.ts
import { SetMetadata } from "@nestjs/common";

export const ROLES_KEY = "roles";
export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);

// roles.guard.ts
import { CanActivate, ExecutionContext, Injectable } from "@nestjs/common";
import { Reflector } from "@nestjs/core";
import { ROLES_KEY } from "./roles.decorator";

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const required = this.reflector.getAllAndOverride<string[]>(ROLES_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    if (!required || required.length === 0) return true; // no @Roles() = open route

    const { user } = context.switchToHttp().getRequest();
    return required.some((role) => user?.roles?.includes(role));
  }
}

@Controller("orders")
@Roles("editor") // class-level default
export class OrdersController {
  @Get()
  list() { /* requires "editor" — inherits the class default */ }

  @Delete(":id")
  @Roles("admin") // method-level override
  remove() { /* requires "admin" — this wins over the class's "editor" */ }
}

Key concept: getAllAndOverride(key, [handler, class]) checks the handler first, then the class, and returns the first one it finds — it does not merge arrays. That order in the array is why a method-level @Roles("admin") completely replaces the class-level @Roles("editor") rather than requiring both. If you actually want both handler and class metadata combined, Reflector also has getAllAndMerge(), which concatenates arrays instead of short-circuiting — reach for it explicitly when "either level can add a role" is the behavior you want.

Stage 4: registering a global guard without losing DI

Back to the intro's bug. app.useGlobalGuards(new RolesGuard(...)) builds the guard outside the container, so any constructor dependency has to be supplied by hand — which is exactly what went wrong. The fix is to register the guard as a provider, using the APP_GUARD injection token from @nestjs/core:

import { APP_GUARD } from "@nestjs/core";

@Module({
  providers: [
    RolesGuard,
    { provide: APP_GUARD, useClass: RolesGuard },
  ],
})
export class AppModule {}

Because RolesGuard is now a normal provider, Nest resolves its constructor the usual way — Reflector (and, in the intro's case, a real UserService) get injected correctly, module-scoped providers work, and Test.createTestingModule can overrideProvider(RolesGuard) in tests the same way it overrides any other dependency, as covered in this series' testing module episode. None of that is available to a guard built with new in main.ts.

Key concept: app.useGlobalGuards() still exists and still works for a guard with zero dependencies — it's not deprecated. The rule is narrower and easy to remember: the moment a guard's constructor needs anything Nest would normally inject, register it through APP_GUARD, not useGlobalGuards().

Stage 5: composing guards — order and "all must pass"

A single request can pass through guards registered at three different scopes at once: global (APP_GUARD, or useGlobalGuards()), controller (@UseGuards() on the class), and method (@UseGuards() on the handler). Nest runs them in that exact order — global, then controller, then method — and within one @UseGuards(A, B) call, in the order listed.

This composition is a logical AND, not a fallback chain: every guard in the sequence must return (or resolve to) true, or the request is rejected at the first one that doesn't. There's no "guard B can override guard A's denial" — a single false anywhere in the chain ends the request immediately, and every guard after it, plus every interceptor and pipe, is skipped entirely.

@UseGuards(ThrottleGuard, RolesGuard) // ThrottleGuard runs first
@Controller("orders")
export class OrdersController {}

If a global AuthGuard is also registered via APP_GUARD, the real order for any route on this controller is: AuthGuard → ThrottleGuard → RolesGuard → (method-level guards, if any) → interceptors → pipes → the handler.

Edge cases and gotchas

A guard that throws vs. a guard that returns false. Returning false produces a generic 403 Forbidden. Throwing a specific exception — throw new UnauthorizedException("Session expired") — gives the client (and your logs) a far more useful signal, and is the idiomatic choice for anything beyond "just deny it."
Reflector needs the exact same metadata key everywhere. SetMetadata(ROLES_KEY, ...) and reflector.getAllAndOverride(ROLES_KEY, ...) must use the identical string (or, better, the same exported constant). A typo in one spot means the guard silently sees undefined and treats the route as unrestricted — this fails open, which is the worst direction for an auth check to fail.
getAllAndOverride vs getAllAndMerge. Covered in Stage 3, but worth repeating because it's the single most common Reflector mistake: reach for getAllAndOverride when a method should be able to fully replace a class default, and getAllAndMerge when both levels should contribute.
WebSocket and microservice guards need a type check. context.switchToHttp() throws if the current call isn't actually HTTP. A guard meant to run across transports should branch on context.getType() ("http", "ws", "rpc") before picking which switchTo*() to call.
A denied guard skips the "before" half of interceptors too. Interceptors run after guards, so a rejected request never reaches even the setup code in an interceptor — only the exception-filter layer sees it.

Best practices

Keep guards to yes/no authorization decisions. If you find yourself mutating the request object inside a guard, that logic usually belongs in middleware (before routing) or an interceptor (after the handler is chosen) instead.
Prefer metadata-driven guards over hardcoded checks. A @Roles()/Reflector pair scales to new routes with zero changes to the guard itself; an if (handler.name === "remove") branch doesn't.
Register anything with a dependency via APP_GUARD, never new Guard(). It's the difference between a guard that's testable and overridable, and one that silently can't be either.
Fail closed, not open. If a metadata lookup comes back undefined because of a wiring mistake, decide what that should mean deliberately (usually: deny), rather than letting !required accidentally mean "allow everyone."
One guard, one concern. A ThrottleGuard and a RolesGuard composed via @UseGuards(ThrottleGuard, RolesGuard) are each easier to test and reuse than one guard doing both jobs.

FAQ

Do guards run before or after middleware?

After. Middleware runs first and doesn't know which controller or handler will end up serving the request; guards run once routing has resolved to a specific handler, which is what lets a guard call context.getHandler().

Can a guard inject a service?

Yes, as long as Nest constructs the guard — via @UseGuards(SomeGuard) (the class) or an APP_GUARD provider. A guard instance you build yourself with new gets none of Nest's dependency injection.

Can I use `@UseGuards()` more than once on the same controller?

Yes — @UseGuards(A, B, C) runs them in that order, and you can also stack a class-level @UseGuards() with a method-level one; both apply, in the global → controller → method order described in Stage 5.

What does a guard returning `false` actually send to the client?

A 403 Forbidden by default, handled by Nest's built-in exception layer. Throw a specific HttpException subclass from inside the guard if you need a different status code or a custom error body.

Is `Reflector` only for guards?

No — interceptors and custom decorators use it too, for the same reason: reading metadata attached to a handler or class via SetMetadata. Guards are just its most common consumer, because "does this route require X" is the canonical authorization question.

Cheat sheet

// A guard is a provider that implements CanActivate.
@Injectable()
export class MyGuard implements CanActivate {
  constructor(private reflector: Reflector) {} // real DI, if registered correctly

  canActivate(ctx: ExecutionContext): boolean | Promise<boolean> {
    const req = ctx.switchToHttp().getRequest();       // the underlying request
    const handler = ctx.getHandler();                  // the exact route method
    const controller = ctx.getClass();                 // the controller class
    return true; // or false, or throw a specific HttpException
  }
}

// Metadata decorator + read-back
export const ROLES_KEY = "roles";
export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);
// method metadata wins over class metadata:
reflector.getAllAndOverride<string[]>(ROLES_KEY, [ctx.getHandler(), ctx.getClass()]);
// both levels contribute instead:
reflector.getAllAndMerge<string[]>(ROLES_KEY, [ctx.getHandler(), ctx.getClass()]);

// Registration — pick based on whether the guard has dependencies
@UseGuards(MyGuard)              // per-route or per-controller, always through DI
app.useGlobalGuards(new MyGuard()); // global, but NO dependency injection
{ provide: APP_GUARD, useClass: MyGuard } // global, WITH dependency injection

Scope	Registration	Runs when	Gets DI?
Method	`@UseGuards(G)` on a handler	Only that route	Yes
Controller	`@UseGuards(G)` on a class	Every route in that controller	Yes
Global (correct)	`APP_GUARD` provider	Every route in the app	Yes
Global (limited)	`app.useGlobalGuards(new G())`	Every route in the app	No

Execution order for one request: global → controller → method, each one an AND — the first false (or thrown exception) stops the chain immediately.

Key takeaways

A guard is a DI provider with a canActivate(context: ExecutionContext) method — not a bare function, and not free of the container's rules.
ExecutionContext gives a guard the underlying request (via switchToHttp()/switchToWs()/switchToRpc()) and the exact handler/class Nest is about to invoke (via getHandler()/getClass()).
Reflector.getAllAndOverride() reads metadata attached with a custom decorator, checking the method before the class, and returns the first match — use getAllAndMerge() when you want both to contribute instead.
app.useGlobalGuards(new G()) skips dependency injection entirely; use the APP_GUARD provider token for any global guard with constructor dependencies.
Guards compose as global → controller → method, and it's a strict AND: any single false or thrown exception stops the request before it reaches the next guard, any interceptor, or the handler.

Ending

The guard from the intro wasn't wrong about what it wanted to check — it was wrong about how it was born. new RolesGuard(...) and { provide: APP_GUARD, useClass: RolesGuard } compile to the same class doing the same check, and only one of them lets Nest's container do its job. That's the whole lesson of guards: they look like plain functions with a canActivate name, but every guarantee they can offer — real dependencies, testability, metadata lookups through ExecutionContext — depends on Nest actually building them. Next time a "protected" route turns out not to be, check the registration line before you touch the guard's logic.

What's the strangest guard bug you've chased down — a missing dependency, a metadata key typo, or something else? 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 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___

localStorage Isn't Free — It's Blocking Your Main Thread

Parsa Jiravand — Sat, 26 Sep 2026 12:25:07 +0000

You add autosave to a text editor. Every few seconds, whatever's in the textarea gets written to localStorage so a refresh — or a crashed tab — doesn't cost the user their draft. You test it with a paragraph. Smooth. Ship it.

Then someone pastes in a 6,000-word draft, and every autosave tick makes the whole page hitch for a beat — the cursor stalls, the animation in the sidebar stutters, keystrokes queue up and land late. Nothing crashed. No error. The console is clean. It just... pauses. Repeatedly. Forever, as long as the draft stays that big.

Guess before you scroll: it's not a bug in your debounce logic. The debounce is fine. The freeze is coming from a function you'd swear is instant, because it always has been — right up until the argument got large.

The obvious fix that doesn't fix it

Your first move is reasonable: you're calling localStorage.setItem too often, so throttle it.

const saveDraft = debounce((text) => {
  localStorage.setItem("draft", JSON.stringify({ text, savedAt: Date.now() }));
}, 2000);

textarea.addEventListener("input", (e) => saveDraft(e.target.value));

Autosaves now fire every two seconds instead of every keystroke. On a small draft, the stutter is gone — but that's because small drafts were never the problem. Paste the same 6,000-word draft back in and the page still hitches, just less often. Every two seconds instead of every keystroke, but each hitch is exactly as long as before.

That's the tell. Debouncing controls frequency. It does nothing to the duration of a single call. If one call to setItem blocks for 40ms, calling it less often gives you fewer 40ms freezes — not shorter ones.

What's actually blocking

localStorage is a synchronous API. Not "usually fast" — synchronously specified. MDN is direct about it: every getItem and setItem call runs to completion on the thread that called it before anything else on that thread can run. No other event handler fires, no frame paints, no requestAnimationFrame callback executes, until that one line returns.

For a short string, "runs to completion" is sub-millisecond — you'll never see it. But your draft isn't a short string. Before it ever reaches setItem, it goes through JSON.stringify on a growing object, and then the storage write itself has to serialize and persist that string. Both steps happen on the same call, on the same thread, with the same guarantee: nothing else runs until it's done. A 5MB draft doesn't make setItem async — it just makes the synchronous part take longer, and the page is unresponsive for exactly that long, every single time you call it.

There's a second cost stacked on top: localStorage only stores strings. Every save round-trips your data through JSON.stringify, and every load round-trips it back through JSON.parse — both synchronous, both scaling with payload size, both adding to the freeze. And you're working inside a ceiling most browsers put at roughly 5MB per origin for all of localStorage combined, draft included. Get there and setItem throws QuotaExceededError instead of saving — which, for an autosave feature, is worse than a stutter.

The fix: an API that doesn't block

IndexedDB solves the actual problem, not a symptom of it. It's asynchronous from the ground up: you open a transaction, call .put(), and get a request object back immediately. The real work — serializing and persisting the value — happens off the synchronous call stack. Your code (and the browser's renderer) keeps running while it does.

function openDraftsDb() {
  return new Promise((resolve, reject) => {
    const req = indexedDB.open("editor", 1);
    req.onupgradeneeded = () => req.result.createObjectStore("drafts");
    req.onsuccess = () => resolve(req.result);
    req.onerror = () => reject(req.error);
  });
}

async function saveDraft(text) {
  const db = await openDraftsDb();
  const tx = db.transaction("drafts", "readwrite");
  tx.objectStore("drafts").put({ text, savedAt: Date.now() }, "current");
  // tx.oncomplete fires later — the call above already returned.
}

Notice what's missing: no JSON.stringify. IndexedDB uses the structured clone algorithm instead of JSON serialization, so you can hand it the plain object — even Dates, Maps, Blobs — and it stores the value directly. And the storage ceiling isn't a fixed 5MB; it's a share of whatever disk space the browser is willing to grant the origin, which you can check with navigator.storage.estimate() and which is typically a large fraction of free disk space, not a hardcoded number.

The trade you're making is real, not free: IndexedDB's API is callback- and event-based and noticeably more ceremony than setItem(key, value). For a handful of small, infrequent values — a theme preference, a feature flag — localStorage's synchronous simplicity is still the right call; the blocking never gets large enough to notice. The line to watch is payload size and write frequency, not "is this data important." A dark-mode toggle can live in localStorage forever. A growing document, a cart with attachments, or anything you write on every keystroke should not.

🎮 Try it yourself

▶️ Open the interactive playground →

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

Numbers in a paragraph don't land the way a stuttering animation does. The playground runs a requestAnimationFrame loop — a dot sliding back and forth, smooth as long as the main thread is free — next to two buttons that write the same payload two different ways. One call blocks the loop. The other doesn't. Watch the dot, not the numbers.

The lesson

"It's just a localStorage.setItem call" is true and also exactly why it's easy to miss — the API looks identical whether the payload is 12 bytes or 12 megabytes, and only one of those is a problem. Debouncing a synchronous call gives you the same freeze, less often. Only an actually asynchronous API — IndexedDB, here — gives you a shorter one.

Go check what you're writing to localStorage on a hot path — an editor, a form draft, anything with attachments or growing text. If the payload can grow past a few dozen KB, that's worth five minutes today. What's the biggest thing you've ever accidentally shoved into localStorage?

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

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

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

Thanks for reading! Let's stay connected:

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

JSON.stringify Is Quietly Deleting Your File Uploads

Parsa Jiravand — Sat, 26 Sep 2026 12:24:36 +0000

QA signs off on the "edit profile" form. Change your display name, hit save, refresh — the new name is there. Ship it.

Two days later: "I uploaded a new profile picture and it just... didn't change?" You check the network tab. The request fired. Status 200 OK. The server logged a successful update. No red text anywhere. By every signal your tools give you, this worked.

It didn't. And the bug isn't in the upload handler, the server, or the image itself — it's already dead by the time the request leaves the browser.

Guess before you scroll: the file never made it into the request body in the first place. Not corrupted. Not rejected. Just — never there.

The code that looks completely fine

Here's roughly what shipped:

form.addEventListener("submit", async (e) => {
  e.preventDefault();
  const data = Object.fromEntries(new FormData(form));
  await fetch("/api/profile", {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(data),
  });
});

This is a pattern you've probably written yourself. FormData reads the form's current values, Object.fromEntries turns that into a plain object, JSON.stringify turns that into a request body. For a name field or an email field, it's exact and correct — the string goes in, the same string comes out the other end.

The <input type="file" name="avatar"> in that same form goes in as a File object. And that's where it quietly falls apart.

What `Object.fromEntries` actually hands you

Log data.avatar right after that first line and it looks completely normal:

console.log(data.avatar);
// File { name: "sunset.jpg", size: 482113, type: "image/jpeg" }

Real file. Real name. Real size. Everything about it says "this is fine, carry on." So you do — straight into JSON.stringify.

console.log(JSON.stringify(data.avatar));
// "{}"

That's the whole bug, in one line. Not an error, not undefined, not the string "[object File]" — an empty JSON object, every single time, for every file, no matter how big or what type. JSON.stringify walks an object's own enumerable properties to build its output. File — and Blob, which it extends — deliberately doesn't expose its data that way. name, size, and type are accessors defined on the prototype, not enumerable data sitting on the instance, and the actual bytes aren't reachable synchronously at all. JSON.stringify finds nothing to walk and does exactly what the spec says: it writes out {}.

So the request that leaves the browser looks like this:

{ "displayName": "Alex Chen", "avatar": {} }

The server receives valid JSON, updates the name, sees avatar: {}, probably ignores a field it doesn't recognize the shape of — and returns 200 OK, because as far as it's concerned, nothing went wrong. Nothing did go wrong, downstream of the browser. The bug already happened, silently, on your side of the wire.

The "fix" that makes it worse

The instinct once you find this is: fine, get the file's actual bytes into the JSON some other way. FileReader.readAsDataURL() will happily hand you a base64 string:

const toBase64 = (file) =>
  new Promise((resolve) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result);
    reader.readAsDataURL(file);
  });

data.avatar = await toBase64(data.avatar); // now it's a string!
body: JSON.stringify(data);

This does work — the image genuinely round-trips now. But you've traded a silent bug for three quiet costs that show up later instead of immediately:

Base64 inflates the payload by roughly a third. A 3 MB photo becomes a ~4 MB string, because base64 spends 4 characters to encode every 3 bytes.
The whole file sits in memory twice — once as the original Blob, once as the decoded string — for as long as the request is in flight.
You've reinvented multipart/form-data, badly, using text encoding for something the browser already ships a binary-safe way to send.

None of that fails a test. It just makes uploads slower and heavier in a way nobody notices until someone tries to upload a 20 MB image from their phone.

The actual fix: stop converting to JSON

FormData was never the problem. Converting it into something else was. fetch accepts a FormData object as a body directly:

form.addEventListener("submit", async (e) => {
  e.preventDefault();
  const data = new FormData(form); // don't unwrap it
  await fetch("/api/profile", {
    method: "PUT",
    body: data, // no headers, no JSON.stringify
  });
});

Two things to notice, both easy to get backwards:

Don't set Content-Type yourself. multipart/form-data requests need a boundary value in the header to separate fields, and fetch generates a fresh, unique one for you when it sees a FormData body. Set the header manually and you'll ship it without a boundary, which breaks the request in a way that's genuinely confusing to debug.
The file's actual bytes travel this time. No encoding step, no size penalty, no extra copy in memory — the browser streams the binary data as part of the multipart body, the same mechanism a plain HTML form has used since the 90s.

The one real trade-off: your server needs to parse multipart/form-data, not application/json — most frameworks have a one-line answer for this already (Express: multer; Node's built-in http: formidable; plenty of others read it natively).

One more thing `Object.fromEntries` was hiding

There's a second gotcha in that first line of code, unrelated to files: Object.fromEntries silently drops duplicate keys, keeping only the last one. Add a checkbox group like <input type="checkbox" name="topics" value="css"> repeated three times, check two boxes, and Object.fromEntries(new FormData(form)).topics gives you exactly one string — not the array you'd expect.

FormData itself never had this problem. formData.getAll("topics") returns every checked value, in DOM order, from the start. It's specifically the trip through Object.fromEntries that quietly collapses them — one more reason to hand FormData to fetch as-is instead of reshaping it first.

🎮 Try it yourself

▶️ Open the interactive playground →

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

The lesson

Any time you're about to call JSON.stringify on something that came out of a <form>, stop for one second and ask what's actually in it. Text fields survive the round trip. Files and repeated-name fields don't — not with an error, just with data quietly missing from the request that already reported success.

FormData isn't a stepping stone to JSON. For anything with a file in it, it's the destination.

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

Go check your own upload forms — if you see Object.fromEntries(new FormData(...)) followed anywhere by JSON.stringify, that's worth a five-minute look today. What's the quietest "it returned 200 but didn't actually work" bug you've shipped?

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

Thanks for reading! Let's stay connected:

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

The Background Task That Waited 40 Seconds for 'Idle'

Parsa Jiravand — Sat, 26 Sep 2026 12:24:05 +0000

You wire up requestIdleCallback to autosave a draft to IndexedDB. Feels like magic on your machine — it fires within a few milliseconds, every time, because your test tab is doing nothing else.

Then it ships. A user scrolls a long feed, glances at a video, types in a chat sidebar — normal, busy, human use of a web page. Somewhere in there, their draft doesn't save for 40 seconds. Sometimes it doesn't save at all before they close the tab.

Nothing crashed. Nothing errored. The callback just never got a moment it was willing to call "idle."

What you probably think it does

The name reads like a promise: schedule this, and the browser will run it soon, whenever it has a spare cycle. That's roughly true on a quiet page. It is not true in general, and the gap between those two is where bugs like the draft-save above come from.

Here's the actual shape of the API:

requestIdleCallback((deadline) => {
  console.log(deadline.timeRemaining()); // ms left in this idle period
  console.log(deadline.didTimeout);       // true if forced by the timeout option
});

timeRemaining() tells you how much of the current idle slice is left — usually a number under 50, sometimes 0. didTimeout tells you whether the browser actually found idle time or gave up and ran you anyway. That second field exists because the first promise — "I'll call you when I'm free" — has no deadline attached to it at all.

Idle time isn't a clock. It's a gap.

The browser looks for idle periods between frames: after it's finished painting, handling input, and running its own housekeeping for that frame, whatever's left over becomes an idle window. If there's nothing left over — because something is animating, a timer fires every 16ms, or the user is mid-scroll — there's no window, and your callback simply doesn't run.

Crucially, there's no ceiling on how long that can go on. A page that keeps finding something to do every frame can starve every requestIdleCallback on it indefinitely. Not "eventually, slowly" — indefinitely, until the page actually goes quiet.

Watch it happen in your own browser: turn up the simulated load below and watch the scheduled callback stop firing.

🎮 Try it yourself

▶️ Open the interactive playground →

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

That slider isn't decorative — it's genuinely keeping your browser tab busy the same way real work does (a rendering loop, a chat widget, a scroll handler). And you can watch the exact mechanism that made the draft-save bug real: the busier the page, the longer (and less predictably) the callback waits.

The timeout option doesn't fix this — it changes what breaks

requestIdleCallback takes a second argument for exactly this problem:

requestIdleCallback(saveTasks, { timeout: 2000 });

This says: if you haven't found idle time within 2000ms, run it anyway. That sounds like the fix — a guaranteed upper bound. It is, but read what you actually got: the browser will now interrupt whatever it's doing to run your callback, didTimeout will be true, and timeRemaining() inside it will report 0. You didn't get a fast idle slot. You got a forced, un-idle execution of code that was written on the assumption it would only ever run when the browser had room to spare.

If that callback does anything nontrivial — serializing a large object, walking a DOM tree — a timeout-forced run can itself become the janky frame you were trying to avoid. The option trades "might never run" for "might run at the worst possible moment." Pick your poison deliberately, per call site, instead of reaching for timeout: 2000 as a reflex.

It isn't Baseline — and the polyfill people write is a footgun

requestIdleCallback ships in Chromium and Firefox. Safari has never implemented it. WebKit's objections to the original design are old and well documented, and there's no sign of that changing, so treat this the same way you'd treat any non-Baseline API: with a fallback, always.

The fallback people reach for is setTimeout, and it's worth writing carefully:

const requestIdle =
  window.requestIdleCallback ??
  ((cb) =>
    setTimeout(() => {
      const start = Date.now();
      cb({
        didTimeout: false,
        timeRemaining: () => Math.max(0, 50 - (Date.now() - start)),
      });
    }, 1));

const cancelIdle = window.cancelIdleCallback ?? clearTimeout;

Note this is a shim for the shape of the API, not a real implementation of idle detection — setTimeout has no idea whether the main thread is actually free. In Safari, code gated on requestIdleCallback runs on a timer instead, with no idle guarantee at all. That's usually fine for genuinely optional work, and it's exactly why the work you defer to this API should be optional in the first place.

Not the same job as `scheduler.yield`

If you've read about scheduler.yield(), it's easy to lump these together as "ways to be nice to the main thread." They solve opposite problems:

scheduler.yield() is for work you need to finish, soon, without blocking the browser while you do it. You yield, the browser catches up on input and paint, and your loop resumes almost immediately, at high priority.
requestIdleCallback is for work you'd like to finish eventually, only if nothing more important is happening — and you're explicitly fine with "eventually" meaning "maybe not for a while."

Use scheduler.yield() (or its setTimeout(0) fallback) for a big loop that has to complete. Use requestIdleCallback for the things that are fine to skip entirely under load: precomputing a search index, pruning an in-memory cache, sending non-critical analytics, prefetching a route nobody's asked for yet.

The fix for the draft that didn't save

Back to the autosave. The bug wasn't calling requestIdleCallback — it was making it the only path to something that had to happen. The fix keeps the idle callback for the common case (cheap, frequent, no rush) and adds a guaranteed path for the case that matters (the tab is closing, right now):

function scheduleAutosave(draft) {
  requestIdle(() => saveDraft(draft), { timeout: 1500 });
}

// Belt and suspenders: this one is not allowed to wait for "idle."
window.addEventListener("pagehide", () => {
  navigator.sendBeacon("/api/drafts", JSON.stringify(pendingDraft));
});

requestIdleCallback handles the frequent, low-stakes saves. pagehide and sendBeacon handle the one save that's actually load-bearing, and they don't ask the browser's permission first.

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

The takeaway

requestIdleCallback isn't a scheduler that guarantees a turn — it's a favor you ask the browser, one it's allowed to keep declining as long as the page stays busy. Use it for work you're genuinely willing to skip, add a timeout only when you've thought through what running late-and-forced actually costs, and never make it the only road to something that has to happen before the tab closes.

Where have you used requestIdleCallback — and did you give it a real fallback, or trust it to always eventually fire? I'm curious how many of us have a draft-save bug like this one sitting in production right now.

🚀 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 Composables: The Shared State Trap (+ Cheat Sheet)

Parsa Jiravand — Tue, 22 Sep 2026 19:37:11 +0000

You build a useCounter() composable, drop <Counter /> on the page twice, and click the first button. Both counters go up.

You didn't copy-paste a bug. You wrote twelve lines of completely ordinary-looking Composition API code, and Vue executed every one of them correctly. The surprise isn't a Vue bug — it's a gap in your mental model of what a composable actually is, and that gap is exactly where a much more expensive version of this same mistake lives: on a server, where "the other counter" is a different user's browser tab.

What you'll learn

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

Explain why two calls to the same composable sometimes share state and sometimes don't
Predict it from reading the composable's source, without running the app
Deliberately design shared (singleton) state when you actually want it
Clean up a composable's side effects so they don't outlive the component that created them
Recognize why this exact bug is more dangerous in server-rendered Vue than in the browser
Keep the cheat sheet at the end open while you build your next composable

Who this is for

You've written at least one composable — a use* function that returns some refs and functions from <script setup>. You don't need to have hit this bug yet; you will recognize it the moment you see it. If ref vs reactive is still fuzzy, Vue Reactivity Explained: ref vs reactive is a good five minutes first — this article builds on it but doesn't require it.

This article is written against Vue 3.5.42, the current stable release (verified via the npm registry, September 2026). Vue 3.6 is still in release candidate; nothing here changes under it — composables are a code-organization pattern, not a runtime feature that Vapor Mode alters.

The problem: two counters, one number
The mental model: a composable is just a function
Stage 1: state that lives inside the function
Stage 2: composables with side effects need cleanup
Stage 3: composables that call other composables
Stage 4: when shared state is what you actually want
Edge cases and gotchas
Best practices
FAQ
Cheat sheet

The problem: two counters, one number

Here's the composable, written the way it looks in a hundred tutorials:

// useCounter.js
import { ref } from 'vue'

const count = ref(0) // looks like "the counter's state" — but whose?

export function useCounter() {
  function increment() {
    count.value++
  }
  return { count, increment }
}

And here's a component that uses it, dropped onto a page twice:

<!-- Counter.vue -->
<script setup>
import { useCounter } from './useCounter'
const { count, increment } = useCounter()
</script>

<template>
  <button @click="increment">Count: {{ count }}</button>
</template>

<!-- Page.vue -->
<template>
  <Counter />
  <Counter />
</template>

Click the first button five times. Both buttons read Count: 5. Nothing crashed, nothing warned you — useCounter() did precisely what its source says: return the one count that exists.

The bug is not in <Counter />. It's a single misplaced line in useCounter.js — and to see which line, you need the rule that explains both the broken version and the correct one.

The mental model: a composable is just a function

A composable has no special relationship to "a component's state." It's a plain JavaScript function, and JavaScript's own scoping rules decide everything.

State declared inside the function body is created fresh every time the function runs. Since <Counter /> calls useCounter() once per component instance, each instance gets its own ref — private state.
State declared outside the function — at module scope, in the file that defines it — is created exactly once, the first time anything imports the module. Every subsequent call to useCounter() returns a reference to that same ref. That's not a bug in the composable pattern; it's how ES modules always work, for the same reason a module-level let cache = new Map() is shared by every caller too.

Vue's Composition API rules (ref, reactive, onMounted, provide/inject, …) never asked where you put your const. You decided that, with ordinary variable scope, before Vue ever entered the picture. The composable naming convention (useXxx) signals what it does, not how many copies of it exist — that second question is answered by reading exactly one thing: is this ref() call inside the exported function, or outside it?

That's the whole model. Everything below is a consequence of it.

Stage 1: state that lives inside the function

Move count inside useCounter, and each call becomes its own closure over its own ref:

// useCounter.js — fixed
import { ref } from 'vue'

export function useCounter(start = 0) {
  const count = ref(start) // created fresh, once per CALL, not once per FILE
  function increment() {
    count.value++
  }
  return { count, increment }
}

Key concept: nothing about the export changed — same function name, same return shape. Only the scope of count moved from module-level to function-level. Now two <Counter /> instances each run useCounter() independently, each closing over its own count, and clicking one leaves the other alone.

This is the default you want almost every time. If you're writing a composable and you haven't deliberately decided otherwise, put the state inside the function.

Stage 2: composables with side effects need cleanup

Composables aren't only about state — they often start something that needs to be stopped. A classic:

// useMousePosition.js
import { ref, onMounted, onUnmounted } from 'vue'

export function useMousePosition() {
  const x = ref(0)
  const y = ref(0)

  function update(e) {
    x.value = e.clientX
    y.value = e.clientY
  }

  onMounted(() => window.addEventListener('mousemove', update))
  onUnmounted(() => window.removeEventListener('mousemove', update)) // <- easy to forget

  return { x, y }
}

Drop the onUnmounted line, and every component that ever used this composable leaves a mousemove listener attached to window forever, each one still running its update closure against a ref nobody reads anymore. It's not a crash — it's a slow, silent leak that only shows up as "the page gets janky after navigating around for a while."

Key concept: a composable's lifecycle hooks (onMounted, onUnmounted, onScopeDispose) tie the side effect to whichever component (or, as Stage 3 shows, effect scope) called the composable. If you start something, you are responsible for stopping it in the matching hook — Vue does not infer the teardown from the setup.

Stage 3: composables that call other composables

Composables compose — useMousePosition might be built from a lower-level useEventListener:

// useEventListener.js
import { onMounted, onUnmounted } from 'vue'

export function useEventListener(target, event, handler) {
  onMounted(() => target.addEventListener(event, handler))
  onUnmounted(() => target.removeEventListener(event, handler))
}

This works fine called from <script setup>, because onMounted/onUnmounted register against the currently running component instance — and during setup(), there is one. It breaks the moment you call it from somewhere that isn't a component, like a Pinia store's setup function running at app-init time, or a plain test file: there's no "current instance" for the hook to attach to, Vue logs a dev warning, and the callback simply never fires.

The general-purpose fix is onScopeDispose, which ties into Vue's effect scope instead of specifically a component instance — and a component's own setup function is itself one:

import { onScopeDispose } from 'vue'

export function useEventListener(target, event, handler) {
  target.addEventListener(event, handler)
  onScopeDispose(() => target.removeEventListener(event, handler))
}

Key concept: onScopeDispose fires whenever the enclosing effect scope tears down — a component unmounting, or an effectScope().stop() call you make yourself outside any component. It's the one cleanup hook that works the same whether the composable is called from a component or from plain code, which is exactly what a composable meant to be reused outside components needs.

If you skipped Vue Reactivity Explained, the same destructuring rule from that article applies here too: if useEventListener returned a reactive() object instead of individual refs, destructuring it in the caller would silently drop reactivity. Composables should almost always return an object of refs (or use toRefs on a reactive one) so a caller can safely write const { x, y } = useMousePosition().

Stage 4: when shared state is what you actually want

Sometimes module-scoped state is the correct design, not a bug — a logged-in user, a theme preference, a WebSocket connection every component should see the same instance of. The fix isn't "always put state inside the function"; it's "put it outside the function on purpose, and say so":

// useAuthUser.js — a deliberate singleton, not an accident
import { ref, readonly } from 'vue'

// Module scope, intentionally: every caller across the whole app
// shares this exact user. This is a global store, not per-call state.
const _user = ref(null)

export function useAuthUser() {
  function login(user) {
    _user.value = user
  }
  function logout() {
    _user.value = null
  }
  // readonly() stops callers from doing `user.value = ...` directly —
  // every write goes through login()/logout(), which is the whole point
  // of centralizing this state in the first place.
  return { user: readonly(_user), login, logout }
}

Key concept: the code that makes this a singleton is identical in shape to the bug from the opening example — a ref declared outside the function. The difference is entirely in intent and in guarding the write path. A comment explaining why this one is module-scoped is not decoration; it's the one piece of information a reader can't get from the code's shape, because the shape is the same as the accidental version.

Edge cases and gotchas

Server-side rendering makes this bug worse, not just different. In the browser, a module-scoped ref is shared across components in one user's page — annoying, but contained. On a Vue SSR server (Nuxt or a custom setup), a Node process typically renders many different users' requests using the same loaded module. A ref created at module scope is created once when the server starts, not once per request — so useAuthUser's state can leak from the user who requested it first into the response sent to the next user. This is the single most important reason "does this composable's state live inside or outside the function" is worth getting right on purpose, not by habit.
Testing a composable outside a component throws or warns. Calling onMounted/onUnmounted with no active component instance triggers a dev-mode warning and does nothing. Wrap the call in effectScope() when unit-testing a composable directly, so lifecycle-style hooks (onScopeDispose) have somewhere to attach:

  import { effectScope } from 'vue'
  const scope = effectScope()
  scope.run(() => {
    const { count, increment } = useCounter()
    increment()
    expect(count.value).toBe(1)
  })
  scope.stop() // triggers any onScopeDispose cleanup registered inside

Hot Module Replacement can hide the bug in dev. Vite's HMR sometimes re-executes a module and resets its module-scope state, which can make a shared-state leak look fixed after a save — then reappear on a full reload. Don't trust "it works now" from an HMR session; reload the page.
getCurrentInstance() is not the fix. It's tempting to reach for it to detect "am I inside a component," but it's explicitly documented as an internal API for advanced/library use, not a general escape hatch — prefer designing the composable so it doesn't need to know.

Best practices

Default to state inside the function. Only hoist state to module scope when you specifically want one shared instance across the whole app.
Say so when you do. A one-line comment ("module-scope singleton, shared across the app") costs nothing and saves the next reader from re-deriving your intent from scope rules.
Return refs, not a raw reactive() object, so callers can destructure without losing reactivity.
Clean up every side effect a composable starts — a listener, a timer, a subscription — with onUnmounted for component-only composables, onScopeDispose for anything meant to be reusable outside a component.
For real app-wide state, reach for Pinia once it grows past one or two values. It gives you the same "one shared store" idea, but with devtools time-travel, SSR-safe store instantiation per request, and a name (defineStore) that makes "this is intentionally shared" obvious from the import alone.

FAQ

Why didn't Vue warn me that my composable's state was shared?

Because there's nothing to warn about — const count = ref(0) at module scope is completely valid JavaScript and Vue reactivity, doing exactly what it's written to do. The "bug" is a mismatch between your intent and the code's actual scope, which no linter can read your mind about.

Does this affect `provide`/`inject` the same way?

No — provide/inject is scoped to the component tree by design; each provider creates its own value for its own descendants, so two unrelated component trees don't share it. The module-scope trap is specific to state declared directly in a .js file outside any function.

Is a composable just a React-style custom hook?

They solve the same problem — extracting stateful logic into a reusable function — but the mechanics differ. A composable's refs are proxies you can read anywhere without a special calling rule, and there is no "rules of hooks" about call order; a custom hook's state is closed over by React's fiber and re-runs the whole function on every render. The shared-state trap in this article has no React equivalent, because React hooks don't have a module-scope option — useState is always per-component.

Should every composable clean up after itself, even ones that don't touch the DOM?

If it started anything — a listener, an interval, a subscription to something outside Vue's reactivity — yes. If it only computed derived values from its inputs (computed, plain functions), there's nothing to clean up; computed refs are garbage-collected with everything else that stops referencing them.

Can I tell from the outside whether a composable shares state?

Only by reading its source (or its docs). The call site — const { count, increment } = useCounter() — looks identical either way. That asymmetry is exactly why Stage 4's naming/comment convention matters: the information isn't visible where you'd need it most.

🎮 Try it yourself

▶️ Open the interactive playground →

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

Cheat sheet

Pattern	Code	Result
Per-caller state (default)	`ref()` declared inside the exported function	Each call to `useX()` gets its own private state
Shared/singleton state	`ref()` declared outside the function, at module scope	Every call to `useX()` returns the same state — intentional or not
Safe destructuring	Return individual `ref`s: `return { count, increment }`	Caller can destructure without losing reactivity
Component-only cleanup	`onUnmounted(() => …)`	Runs when the owning component unmounts
Reusable-anywhere cleanup	`onScopeDispose(() => …)`	Runs when the enclosing effect scope stops — component or manual `effectScope()`
Protect a singleton's writes	`return { user: readonly(_user), login, logout }`	Callers can read but must go through your functions to write
Test a composable in isolation	`effectScope().run(() => { … })`, then `.stop()`	Gives lifecycle-style hooks somewhere to attach outside a component
SSR danger sign	A module-scope `ref` holding per-user data (auth, cart, …)	Can leak between requests on a server — make it request-scoped or use Pinia

Key takeaways

A composable is a function first; JavaScript's own variable scope — not anything Vue-specific — decides whether its state is private per call or one shared singleton.
State inside the function body is the safe default; state outside it is a deliberate design choice that deserves a comment.
Every side effect a composable starts needs a matching cleanup, via onUnmounted or the more general onScopeDispose.
The same "module scope = shared" rule that causes two counters to double-count in the browser can leak one user's data into another user's response on an SSR server — treat it as a correctness issue, not just a UI quirk.

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

Ending

Those two counters that moved together weren't broken — they were exactly one ref doing exactly what a ref declared outside a function always does. Once you can see that scope decision sitting in the source, every "why are these two components sharing state" question stops being a mystery and starts being a one-line answer you can find by reading, not debugging.

Where has this bitten you — a shared composable, or the SSR version of it? Tell me in the comments.

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

Thanks for reading! Let's stay connected:

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

The Dropdown You've Been Faking for a Decade

Parsa Jiravand — Tue, 22 Sep 2026 19:36:39 +0000

Design wants a country picker. Nothing fancy — a dropdown, a small flag icon next to each name. You reach for <select>, type the first <option>, and hit the wall every frontend dev hits eventually: an <option> can only ever show text. No <img>, no icon span, nothing. The browser renders whatever markup you put inside it as a plain string.

So you do what everyone does. You build a fake one.

The dropdown you build instead

A <div role="listbox">, a button that toggles it, <div role="option"> children with real icons inside, arrow-key handlers, a click-outside listener to close it. It's maybe 150 lines. It works in the demo. Ship it.

<div class="select" id="country-select">
  <button aria-haspopup="listbox" aria-expanded="false">🇨🇦 Canada</button>
  <div role="listbox" hidden>
    <div role="option" data-value="ca">🇨🇦 Canada</div>
    <div role="option" data-value="jp">🇯🇵 Japan</div>
    <div role="option" data-value="br">🇧🇷 Brazil</div>
  </div>
</div>

Then someone drops this select inside a card component — rounded corners, overflow: hidden so a stray image never bleeds past the border radius. Totally normal CSS. And now the popup, which is just a child <div> positioned absolute, gets sliced off at the card's edge the moment it's taller than the space below the trigger.

Try it — watch the fix disappear back into the bug

🎮 Try it yourself

▶️ Open the interactive playground →

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

You didn't do anything wrong. overflow: hidden clips any descendant, and a hand-built popup is, structurally, just a descendant. The standard escape hatch is position: fixed plus getBoundingClientRect() to glue the popup under the trigger by hand — and now you're also re-running that math on every scroll and resize event, and remembering to tear the listeners down when the select unmounts. None of this is exotic. It's just work the native <select> used to do for you, that you signed back up for the moment you needed one icon.

And the part that doesn't show up in a demo video: keyboard behavior. Type-ahead (press "j" and jump to "Japan"), Home/End, wraparound at the list's edges, closing on Escape and returning focus to the trigger, announcing the right state to a screen reader as options are highlighted — a real <select> gets every one of those for free, in every browser, on every OS. The WAI-ARIA Authoring Practices listbox pattern exists as a reference implementation precisely because getting all of that right by hand, consistently, is genuinely hard. Most homegrown dropdowns implement a fraction of it and call it done.

What actually changed

<select> now has an opt-in that unlocks styling without giving up any of that native behavior:

select {
  appearance: base-select;
}

/* the popup is now a real, styleable target */
select::picker(select) {
  border-radius: 12px;
  border: 1px solid #2a2f3a;
}

Two things happen the moment you set appearance: base-select. First, <option> stops being text-only — it can hold real markup, so the flag icon goes right back where you originally wanted it:

<select>
  <button>
    <selectedcontent></selectedcontent>
  </button>
  <option value="ca"><img src="/flags/ca.svg" alt="" /> Canada</option>
  <option value="jp"><img src="/flags/jp.svg" alt="" /> Japan</option>
  <option value="br"><img src="/flags/br.svg" alt="" /> Brazil</option>
</select>

That <selectedcontent> element is new too — it mirrors whatever content the chosen <option> holds into the closed button, so the flag shows up on the trigger, not just inside the open popup.

Second, and this is the part that actually kills the clipping bug from the wrong-way section: ::picker(select) doesn't render as a descendant <div> at all. It's promoted to the top layer — the same rendering layer <dialog> and the Popover API use — so it paints above the entire page, unclipped by any ancestor's overflow: hidden, with no z-index or position: fixed math required. The exact bug in the playground above simply can't happen to it, because it was never inside the clipping container to begin with.

The honest caveat

This is a real, working CSS feature — not a proposal — but support isn't universal yet. It shipped first in Chromium browsers; Firefox and Safari have it in progress at various stages. Check caniuse before you rely on it, and reach for it as progressive enhancement: wrap the opt-in behind @supports (appearance: base-select) and let browsers without support fall back to a plain <select>, which still works, still submits, still has icon-free but fully accessible options. You lose the flags, not the form.

@supports (appearance: base-select) {
  select { appearance: base-select; }
}

That's the whole migration. No polyfill, no JS fallback path to maintain — the feature detection is the fallback.

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

The payoff

The custom <div role="listbox"> component your team maintains — the one with the scroll listener and the getBoundingClientRect() call and the open GitHub issue about it not closing right on iOS — was never really a design requirement. It was a workaround for <option> being text-only and the popup being an ordinary, clippable <div>. Both of those are gone now, behind one CSS property and one new element.

Are you still shipping a hand-rolled dropdown for something this small, or are you already behind @supports on the real thing? I'd genuinely like to know which.

🚀 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 proxy.ts Explained (with Cheat Sheet)

Parsa Jiravand — Tue, 22 Sep 2026 19:36:08 +0000

Your team wrote middleware.ts carefully — Edge-safe imports only, jose instead of jsonwebtoken, no direct database calls — because that's what Edge middleware demanded. Then you upgraded to Next.js 16, skimmed the release notes, and moved on. Nothing broke. Which is exactly the problem: middleware.ts still runs, but it's now the deprecated way to do the one job every non-trivial app needs — checking a request before a single line of your app runs. The framework renamed the file, moved the runtime under it, and left the old name working just long enough for teams to miss the change entirely.

What you'll learn

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

Explain what proxy.ts is, why Next.js 16 renamed middleware.ts to it, and what actually changed under the hood.
State exactly which runtime proxy.ts runs on — and why you can no longer choose.
Migrate an existing middleware.ts file with the official codemod, including the config options that renamed alongside it.
Recognize the one capability trade Next.js made, and decide whether it affects your app.
Write a proxy.ts that checks auth, sets a header, and rewrites a request — the shape that covers most real uses.

Who this is for

You've shipped a Next.js App Router app and have (or have used) a middleware.ts file for things like auth checks or redirects. You don't need prior Edge-runtime experience — this article explains what that runtime was and why it mattered.

The problem: a boundary with two names and a hidden runtime
The mental model: proxy.ts is the network boundary, not a request handler
Migrating middleware.ts to proxy.ts, step by step
Edge cases and gotchas
Best practices
FAQ
Cheat sheet
Key takeaways

The problem: a boundary with two names and a hidden runtime

This article is written against Next.js 16.3 (the current Active LTS release, verified against the framework's own file-convention and upgrade docs, and its GitHub releases, in September 2026). If you're reading this from a much later version, re-check the docs linked below before trusting a specific detail — that's the honest habit this series keeps asking of you, and this topic is exactly why.

Here's the wrong-way-first version, because it's what most teams actually did. A Next.js 15 app has this middleware.ts:

// middleware.ts — Next.js 15, Edge runtime (the only option)
import { NextResponse } from "next/server";
import { jwtVerify } from "jose"; // Edge-safe; jsonwebtoken would not run here

export async function middleware(request: Request) {
  const token = request.headers.get("cookie")?.match(/session=([^;]+)/)?.[1];
  if (!token) return NextResponse.redirect(new URL("/login", request.url));

  try {
    await jwtVerify(token, secretKey); // must be Edge-runtime-compatible
    return NextResponse.next();
  } catch {
    return NextResponse.redirect(new URL("/login", request.url));
  }
}

export const config = { matcher: ["/dashboard/:path*"] };

Every choice in that file — jose over jsonwebtoken, no direct Postgres client, no fs — exists because Edge middleware ran on a restricted, non-Node runtime. That constraint was real and it shaped how an entire generation of Next.js auth code got written.

Then Next.js 16 ships, and the docs start talking about proxy.ts instead. The team upgrades. middleware.ts still runs — Next.js kept it working on purpose — so nothing visibly breaks, and the rename gets filed under "not our problem yet." Two things go quietly wrong from there:

New code in the same repo starts appearing as proxy.ts (copied from a blog post, a teammate's other project, or the docs), and now the app has both a middleware.ts and a mental model split between two names for the same job.
Someone "helpfully" migrates the file and copies the runtime opt-in along with it:

// proxy.ts — this line is now meaningless
export const runtime = "edge"; // ❌ ignored — proxy always runs on Node.js

proxy.ts doesn't fail loudly here — it just runs on the Node.js runtime regardless, because that runtime cannot be configured. The Edge runtime isn't an option for proxy.ts at all. If your mental model is still "Edge middleware, just renamed," you'll misjudge what you can and can't do inside it.

The mental model: proxy.ts is the network boundary, not a request handler

The mental model: proxy.ts is the one file that sits in front of your entire app, on every request that matches its matcher, and runs before the App Router resolves a route — before any layout, page, Server Component, or Server Action executes. Next.js 16 renamed it from middleware.ts specifically to stop you from thinking of it as a request handler in the Express sense (a function in a chain, alongside your route logic). It's a network boundary: the place where you decide whether a request is even allowed to reach the app, and what it's allowed to carry in with it (a header, a rewritten path, a redirect).

The rename came with a runtime decision, not just new vocabulary: proxy.ts runs exclusively on the Node.js runtime. There is no export const runtime = "edge" for it — the option doesn't exist, because a proxy that always runs the same way, in the same environment, is the entire point. middleware.ts is still there for teams that specifically need Edge behavior, but it's documented as deprecated, scheduled for removal in a future major version. You're not choosing between two files going forward; you're on a deprecation clock.

What that buys you: proxy.ts can use anything the Node.js runtime supports — Node's built-in crypto, a real database driver for a session lookup, any npm package that assumes Node — without auditing it for Edge compatibility first. What it costs you: if your app specifically wanted Edge's global, low-latency execution for this boundary, that option is gone for new code. For the overwhelming majority of auth/redirect/rewrite logic, that trade is invisible; for a handful of latency-critical, globally-distributed checks, it's worth knowing about before you commit.

Migrating middleware.ts to proxy.ts, step by step

Step 1 — run the codemod, don't hand-edit. Next.js ships an automated migration:

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

This renames middleware.ts → proxy.ts, renames the exported middleware function to proxy, and updates the config keys that renamed alongside it (for example skipMiddlewareUrlNormalize → skipProxyUrlNormalize, and experimental.middlewareClientMaxBodySize → experimental.proxyClientMaxBodySize in next.config.js). Run it, then read the diff — a codemod is a strong first draft, not a substitute for review.

Key concept: the codemod changes names, not behavior. Whatever your middleware did, your proxy does identically — the boundary's job hasn't moved, only its label and its guaranteed runtime.

Step 2 — delete any runtime opt-in. If your old file had export const config = { runtime: "edge" } or similar, remove it. It has no effect on proxy.ts, and leaving it in is the kind of thing that confuses the next engineer more than it confuses the framework.

Step 3 — keep the matcher, unmodified. The matcher config that scopes which paths trigger the boundary is unchanged:

// proxy.ts
export const config = {
  matcher: ["/dashboard/:path*", "/api/protected/:path*"],
};

Step 4 — now you can simplify, if it helps. Because you're guaranteed Node.js, you can replace an Edge-safe workaround with the straightforward version, if one exists:

// proxy.ts — Next.js 16, Node.js runtime (the only option, and now a guarantee)
import { NextResponse } from "next/server";
import { jwtVerify } from "jose"; // still works fine — no need to rip it out
import type { NextRequest } from "next/server";

export function proxy(request: NextRequest) {
  const token = request.cookies.get("session")?.value;
  if (!token) {
    const loginUrl = new URL("/login", request.url);
    loginUrl.searchParams.set("from", request.nextUrl.pathname);
    return NextResponse.redirect(loginUrl);
  }
  return NextResponse.next();
}

export const config = { matcher: ["/dashboard/:path*"] };

Key concept: nothing here had to change — jose runs fine on Node.js too. The point isn't "rewrite everything," it's that you're no longer required to reach for an Edge-safe library when a plain Node one would do, and you won't hit a surprise if a dependency assumes Buffer or crypto.createHmac exists.

Edge cases and gotchas

middleware.ts still works — for now. Next.js 16 didn't remove it; it's deprecated and slated for removal in a future major version. If you need the Edge runtime specifically (for its global execution model), keep using middleware.ts with its runtime opt-in and track the deprecation notice for when that stops being an option.
The runtime is not configurable, in either direction. You can't opt proxy.ts into Edge, and there's no flag to force middleware.ts onto Node.js. The two files map to two fixed runtimes; migrating means accepting the new one.
Config keys renamed, not just the file. If your next.config.js sets skipMiddlewareUrlNormalize or experimental.middlewareClientMaxBodySize, those need the proxy-prefixed equivalents after migration — the codemod handles this, a manual rename easily misses it.
This doesn't remove the Edge runtime from Next.js. Route Handlers and pages can still opt into the Edge runtime where it's supported. The one place Edge specifically disappeared is the network-boundary file — don't over-generalize the change to the rest of the framework.
The rewrite/redirect logic itself hasn't changed. NextResponse.next(), .redirect(), .rewrite(), and reading/writing cookies and headers all work the same way in proxy.ts as they did in middleware.ts. The migration is about the file's name, its exported function's name, and its runtime — not its API.

Best practices

Reach for proxy.ts for boundary decisions, not business logic: auth gating, locale/region redirects, A/B routing, header injection, and blocking bad requests before they cost you a route render. If a check needs your app's Server Components or database models to decide, it usually belongs past the boundary, not inside it.
Run the codemod on every middleware.ts you own, even ones that "still work fine." The deprecation clock is real, and doing it now — while you can compare the diff against a file you understand — is cheaper than doing it later under a removal deadline.
Keep the matcher as narrow as the job needs. A boundary that runs on every request, including static assets it doesn't care about, is pure overhead; scope it to the paths that actually need the check.
Don't move Edge-specific code into proxy.ts unexamined. If a library was chosen specifically for Edge compatibility, it's fine to leave it — but don't assume you now need a different library, either. Change what the runtime actually requires you to change, nothing more.

FAQ

Is `proxy.ts` a completely new file, or a rename?

It's a rename with a runtime attached. Same conceptual job as middleware.ts — code that runs before the App Router resolves a route — but the exported function is now called proxy, the file is proxy.ts, and it always runs on the Node.js runtime.

Do I have to migrate right now?

No — middleware.ts still works in Next.js 16. But it's documented as deprecated and due for removal in a future major version, so treat this as scheduled work, not optional cleanup.

Can I run `proxy.ts` on the Edge runtime if I really want to?

No. The runtime for proxy.ts is fixed to Node.js and isn't configurable. If your use case specifically needs Edge, that's what middleware.ts remains for, while it's still available.

Will the migration change what my auth/redirect logic does?

It shouldn't. The codemod renames the file, the function, and the handful of config keys that renamed with it. The request/response API — NextResponse.next(), .redirect(), .rewrite(), cookies, headers — is unchanged.

Does this affect Route Handlers or pages that use the Edge runtime?

No. The Edge-runtime removal is specific to the network-boundary file. Route Handlers and pages can still opt into Edge where Next.js supports it there.

Cheat sheet

Task	Next.js 16 way	Notes
File name	`proxy.ts` (was `middleware.ts`)	Old name still works, deprecated
Exported function	`export function proxy(...)`	Was `export function middleware(...)`
Runtime	Node.js only, not configurable	No Edge option for `proxy.ts`
Scope which paths run it	`export const config = { matcher: [...] }`	Unchanged from `middleware.ts`
Migrate automatically	`npx @next/codemod@canary middleware-to-proxy`	Renames file, function, and config keys
Renamed config keys	`skipMiddlewareUrlNormalize` → `skipProxyUrlNormalize`; `experimental.middlewareClientMaxBodySize` → `experimental.proxyClientMaxBodySize`	Codemod handles these
Need Edge runtime specifically	Keep `middleware.ts` for now	Tracked for future removal
Redirect / rewrite / headers API	`NextResponse.next()` / `.redirect()` / `.rewrite()`	Identical to `middleware.ts`

// The canonical proxy.ts shape: check, then let through or redirect
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function proxy(request: NextRequest) {
  const isAllowed = /* your boundary check — auth, locale, A/B, etc. */ true;
  if (!isAllowed) return NextResponse.redirect(new URL("/login", request.url));
  return NextResponse.next();
}

export const config = { matcher: ["/dashboard/:path*"] };

🎮 Try it yourself

▶️ Open the interactive playground →

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

Key takeaways

proxy.ts is Next.js 16's rename of middleware.ts — same job (the network boundary in front of your app), new name, and a fixed Node.js runtime that can't be configured.
middleware.ts still runs today, but it's deprecated; the official codemod (npx @next/codemod@canary middleware-to-proxy) migrates the file, the function name, and the config keys together.
The Edge runtime isn't gone from Next.js — it's gone specifically from this one boundary file, so don't over-apply the change to Route Handlers or pages.
Because the boundary now runs on Node.js unconditionally, you can use ordinary Node-only libraries there without an Edge-compatibility audit — but you don't have to change code that already worked.

This series has already covered two things proxy.ts sits in front of: the request eventually reaches Server Actions and the mutation flow they run, and whatever renders downstream is shaped by Cache Components and what streams versus what's cached. Neither is required reading here, but both make more sense once you know what already ran before them.

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

Your middleware.ts still works today — but it's running on borrowed time and an assumption about the Edge runtime that no longer holds for new code. Migrate it this week, while the diff is small and the reasoning is fresh, rather than in a rush when the removal notice finally lands. What's the messiest thing your boundary file currently does — and would you trust it to run on Node.js without a second look?

🚀 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 Writing JavaScript To Fix `100vh` On Mobile

Parsa Jiravand — Tue, 22 Sep 2026 19:35:37 +0000

Your hero section is height: 100vh. Big background image, headline centered, a CTA button pinned near the bottom. You check it in the browser, check it in the iOS simulator, ship it.

Then the support tickets come in: "the sign-up button is cut off." You open it on your own phone to confirm — and it looks fine. Scroll down an inch, though, and there's a sliver of button peeking out from under where the fold should be.

Guess what's different between your simulator and a real phone in someone's hand — before you scroll.

The fix everyone reaches for first

The instinct is to blame the button, not the unit. Add padding, shrink the image, tweak breakpoints. None of it holds, because the box itself is the wrong size — 100vh is taller than what the user can actually see, and no amount of internal spacing fixes a container that's bigger than its own screen.

So the real fix people land on, for years now, has been JavaScript:

function setViewportHeight() {
  document.documentElement.style.setProperty(
    "--vh",
    `${window.innerHeight * 0.01}px`
  );
}

setViewportHeight();
window.addEventListener("resize", setViewportHeight);

.hero {
  height: calc(var(--vh) * 100);
}

This works. It's also been copy-pasted into thousands of codebases as a shrug-emoji workaround — a resize listener recalculating a custom property, just so CSS can know something the browser already knows. It renders with the wrong height for one frame before the script runs. It has to be re-wired for every new full-screen element. And on some Android keyboards, "resize" fires in ways that make the hero jump while someone's mid-scroll.

You're not wrong to reach for it. vh really doesn't tell you what you think it tells you.

What `100vh` actually measures

Here's the part that makes the bug feel random instead of consistent: 100vh isn't measuring "the screen right now." It's measuring the browser's largest possible viewport — the height you'd get if the address bar and toolbar were fully collapsed.

On iOS Safari, the address bar collapses when you scroll down and reappears when you scroll up or land on a fresh page. 100vh was sized for the collapsed state the whole time — so the moment that bar is visible (which, on a page load, it always is), your "full screen" hero is taller than the actual visible area by exactly the height of that bar. The bottom of your hero, CTA included, sits behind it.

And for years, Chrome on Android handled the same unit differently — sizing vh around the smallest viewport instead, bar included. Two major browsers, one CSS unit, two different answers to "how tall is the screen." That's why this bug never had a clean repro: it depended on the browser, the scroll position, and whether the user had just loaded the page or scrolled once already.

vh isn't lying. It's answering a question — "how tall is this viewport at its largest?" — that nobody actually asked.

The units that were built to answer the real question

Since 2022, every major browser engine ships three more precise viewport units, and they turn that whole JavaScript workaround into one CSS declaration:

svh — small viewport height. The height when browser UI (address bar, toolbar) is fully expanded. This is the safe, stable floor: content sized to svh always fits, bars showing or not.
lvh — large viewport height. The height when browser UI is fully collapsed. This is what vh was already measuring on iOS Safari.
dvh — dynamic viewport height. Tracks the real, current visible height, live, recalculating as the address bar shows and hides.

Swap the unit, delete the JavaScript:

.hero {
  height: 100vh; /* fallback for browsers that don't parse dvh */
  height: 100dvh;
}

Browsers that don't recognize dvh treat that whole declaration as invalid and ignore it — so the 100vh line above it quietly stands as the fallback, no @supports block required. Everywhere dvh is understood, the second line wins and the hero tracks the real viewport, live, as the bar animates in and out. No resize listener, no custom property, no one-frame flash of the wrong size.

The same trio exists for width (svw/lvw/dvw) and for logical dimensions (svi/lvi/dvi, svb/lvb/dvb, for writing-mode-aware layouts) — same three questions, different axis.

Try it before you keep reading: the playground below simulates a phone's address bar collapsing as you scroll, with three stacked panels — one sized in vh, one in svh, one in dvh — so you can watch all three respond (or fail to respond) to the exact same scroll.

🎮 Try it yourself

▶️ Open the interactive playground →

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

Pick the right one, not just the new one

Reaching for dvh everywhere trades one bug for a subtler one. Because dvh recalculates while the address bar is mid-animation, anything sized with it visibly resizes as the user scrolls — a hero that gently grows and shrinks by fifty-odd pixels as the bar slides. For a full-bleed section that's supposed to feel locked to the screen, that's the right behavior. For, say, a sticky modal or a fixed bottom sheet, that same live resize reads as jitter.

A rough rule that holds up in practice:

dvh for full-bleed sections you want to genuinely hug the visible viewport — landing page heroes, full-screen intro panels.
svh for anything that must never get cut off, even worst-case — a modal's max-height, a "fits on one screen" onboarding step. It's the pessimistic, always-safe number.
lvh rarely, when you specifically want the old 100vh behavior on purpose (matching a background that's meant to bleed past the visible edge).

Support is solid enough to reach for today without a polyfill: Safari since 15.4 (March 2022), Chrome and Edge since 108 (December 2022), Firefox since 101 (May 2022). The height: 100vh; height: 100dvh; stacking pattern above is your fallback for anything older — no feature query needed, because the invalid-property-drop behavior does the work for you.

The takeaway

100vh was never broken — it was always precisely, consistently answering "how tall is this viewport with the browser chrome fully out of the way," which is a real answer to a question almost nobody meant to ask. dvh, svh, and lvh let you ask the actual question directly, in CSS, and delete the resize listener that's been standing in for them.

If you've got a --vh custom property hack sitting in a codebase right now — how old is it, and what would it take to rip out?

🧠 Test yourself

Think it clicked? Take the 7-question quiz →

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

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

Thanks for reading! Let's stay connected:

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

React Derived State: Why That useState Is Probably a Bug

Parsa Jiravand — Sun, 20 Sep 2026 16:27:06 +0000

You add a search box to a todo list. todos is state, filter is state, and — because the filtered list "depends on" both — you add a third state variable, visibleTodos, and a useEffect that recalculates it whenever todos or filter changes. It works. Then, months later, someone adds a bulk "complete all" button that updates todos directly, and the list on screen doesn't change for a beat. No error, no warning — just a stale list until the next keystroke nudges the Effect awake.

Nothing here is exotic. It's one of the most common bugs in React codebases, and it exists because a value that should have been computed got stored instead.

This is episode two of React Deep Dive, on what React itself decides rather than JavaScript wearing a React import. This one is about a decision every component makes constantly and mostly gets right by accident: which values belong in state, and which ones only look like they do.

This article is written against React 19.3 (verified against the React blog and GitHub releases, 19.3.0, published September 9, 2026) and the React Compiler at 1.0, stable since October 2025. Everything here assumes React 19-era function components and hooks.

What you'll learn

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

Recognize derived state — a value fully determined by props or other state — versus state that genuinely needs to exist
Explain, precisely, why syncing a derived value with useEffect + setState costs an extra render and can drift
Replace that pattern with a plain calculation during render, and know when to reach for useMemo instead
Handle the harder case — resetting or adjusting state when a prop changes — without an Effect
Tell the difference between "derived from what I already have" and "genuinely new information," which is the actual boundary

Who this is for

You've written function components with useState and useEffect, and you've shipped at least one bug where two pieces of state disagreed with each other. No prior knowledge of the React Compiler is assumed.

The problem: a list that lags behind its own data
The mental model: state is memory, render is a formula
Stage 1: the naive fix and why it still isn't right
Stage 2: delete the state, keep the value
Stage 3: when the calculation is actually expensive
Stage 4: the harder case — resetting state when a prop changes
Edge cases and gotchas
Best practices: the actual test
FAQ
Cheat sheet
Key takeaways

The problem: a list that lags behind its own data

Here's the todo list from the opening, written the way it tends to get written the first time:

function TodoList({ todos }) {
  const [filter, setFilter] = useState("all");
  const [visibleTodos, setVisibleTodos] = useState(todos);

  useEffect(() => {
    setVisibleTodos(
      filter === "all" ? todos : todos.filter((t) => t.done === (filter === "done"))
    );
  }, [todos, filter]);

  return (
    <>
      <FilterButtons value={filter} onChange={setFilter} />
      <ul>
        {visibleTodos.map((t) => <li key={t.id}>{t.text}</li>)}
      </ul>
    </>
  );
}

This runs. It even looks reasonable — visibleTodos "depends on" todos and filter, so it lives in an Effect that watches both. But walk through what actually happens on a single click of a filter button:

setFilter("done") schedules a render. TodoList re-renders with the new filter but the old visibleTodos — React hasn't run your Effect yet, because Effects run after the DOM commits.
The user briefly sees the wrong list (all todos, not just the done ones), for one paint.
The Effect then runs, calls setVisibleTodos, and schedules a second render.
React renders again, this time with the correct filtered list.

That's two full render passes and one commit doing visible work for a value you could have had correct on the first pass. And the bulk "complete all" bug from the intro is the same mechanism from the other direction: something mutates todos through a path that doesn't also re-run this specific Effect's mental model correctly, or a later render reads visibleTodos before the Effect catches up, and the two state variables disagree.

None of this is a React bug. React is doing exactly what you asked: keep two separate pieces of memory, and use an Effect to keep the second one following the first. The bug is that visibleTodos was never independent information — it was a formula wearing state's clothes.

The mental model: state is memory, render is a formula

Split every value your component touches into two categories:

State is memory. It's the only thing React can't reconstruct on its own — user input, a value from a request, anything genuinely new that arrived from outside this render.
A derived value is anything you could recompute, right now, from state and props you already have. It isn't information; it's a formula over information.

The mental model: if you can write const x = f(props, otherState) and get the right answer every time, x was never state — it's a calculation, and calculations belong in the render body, not in a useState/useEffect pair. An Effect exists to synchronize your component with something outside React — the DOM, a subscription, a network request, document.title. Using one to copy one piece of React state into another piece of React state is React talking to itself through a detour, and the detour is where the extra render and the drift both come from.

This reframes useEffect itself: it isn't "the place derived stuff goes," it's "the place synchronization with the outside world goes." A value computed from props and state was never outside anything.

Stage 1: the naive fix and why it still isn't right

A common first correction is to memoize inside the Effect, or to add a guard so it "only runs when needed":

useEffect(() => {
  const next = filter === "all" ? todos : todos.filter((t) => t.done === (filter === "done"));
  if (next !== visibleTodos) setVisibleTodos(next);
}, [todos, filter]);

Key concept: this treats the symptom (an extra render) without touching the cause (a second copy of information that has to be kept honest). The stale-paint flash from step 2 above is still there — the Effect still runs after the commit, not before it — and you've added a comparison that has to be maintained forever. The state was the mistake; no amount of guarding the Effect fixes that.

Stage 2: delete the state, keep the value

The actual fix removes code:

function TodoList({ todos }) {
  const [filter, setFilter] = useState("all");

  const visibleTodos =
    filter === "all" ? todos : todos.filter((t) => t.done === (filter === "done"));

  return (
    <>
      <FilterButtons value={filter} onChange={setFilter} />
      <ul>
        {visibleTodos.map((t) => <li key={t.id}>{t.text}</li>)}
      </ul>
    </>
  );
}

No visibleTodos state, no Effect, no second render, no drift — because there is only one piece of information (todos and filter) and one formula over it. Click a filter button now, and TodoList renders exactly once, with the correct list, because the correct list was never anything but todos and filter combined.

Key concept: a value that's recomputed on every render is not "wasted work" by default — rendering is supposed to be cheap and pure. Reach for a second render only when React genuinely needs one; a plain const inside the component body isn't a render, it's a step within the one you're already doing.

Stage 3: when the calculation is actually expensive

Sometimes the formula really is costly — sorting or filtering thousands of rows, for instance — and recomputing it on every render (including ones triggered by something unrelated, like typing in an unrelated text field on the same component) is wasteful. That's what useMemo is for:

const visibleTodos = useMemo(
  () => (filter === "all" ? todos : todos.filter((t) => t.done === (filter === "done"))),
  [todos, filter]
);

useMemo still computes the value during render, synchronously, before anything paints — it just skips redoing the work if todos and filter are unchanged since last time. It is a performance optimization, not a place to put a second copy of the answer, and it produces no second commit the way the Effect version did.

Episode one of this series (React Compiler 1.0: What useMemo You Can Delete) covers the other side of this: with the Compiler enabled, this specific useMemo is usually one you no longer have to write by hand — the compiler memoizes it for you. What it will never do is turn a useEffect-plus-setState pair back into a derived value; that rewrite is a design decision, not something a compiler can safely infer, because it can't know your Effect wasn't also doing something with genuine side effects on the outside world.

Stage 4: the harder case — resetting state when a prop changes

Sometimes what looks like "syncing derived state" is really about a prop change that should reset unrelated state — a <ProfilePanel userId> where switching users should clear a draft comment, for instance. The Effect-shaped instinct is the same trap:

// Don't do this
function ProfilePanel({ userId }) {
  const [comment, setComment] = useState("");
  useEffect(() => {
    setComment("");
  }, [userId]);
  // ...
}

This has the identical problem as Stage 1: one render with the stale comment, then an Effect-triggered second render that clears it. The fix here isn't a calculation — comment genuinely is state, freely typed by the user, not derivable from anything — the fix is telling React this is a different instance of the component, which is a subject the first episode of this series covered in depth: giving the component a key.

<ProfilePanel userId={userId} key={userId} />

When userId changes, React doesn't update the existing ProfilePanel instance — it discards it and mounts a fresh one, with comment back at its initial value, in the same render, no Effect involved. See React Re-render vs Remount: What Actually Triggers Each for exactly how React decides between updating an instance and replacing it. The two bugs in this article and that one are the same shape from two directions: this one is about values you shouldn't have kept as separate memory at all; that one is about memory you correctly kept, but attached to the wrong lifetime.

🎮 Try it yourself

▶️ Open the interactive playground →

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

Edge cases and gotchas

Adjusting only some state when a prop changes. If a key reset would throw away too much (say, only one field should clear, the rest should survive), React's own guidance is to compute that one field during render by comparing the current prop against a previous-value stored in state — a narrow, deliberate escape hatch, not a general pattern, and one that reads oddly enough that it deserves a comment explaining why it isn't an Effect.
Fetched data is not derived state. todos arriving from an API is genuinely new information your component couldn't calculate on its own — that's real state (or better, a request-lifecycle tool that isn't plain useState). The rule in this article is about values computed from data you already hold, not the data itself.
Derived values that also need to survive a remount. If a formula's result should persist across a key change on purpose, it can't be "just a calculation" anymore — you've described state, and that's fine; just be honest that it is one.
useMemo is not a correctness tool. It changes when the calculation reruns for performance, never what the calculation returns. Never rely on useMemo to skip work that has an externally visible side effect — that's what useEffect is for, and the two aren't interchangeable.
Context values built from derived state. A useMemo-wrapped object passed through Context.Provider is a very common and correct use of memoization — it stops every consumer from re-rendering just because the provider re-rendered with a fresh object literal. That's a real performance concern this pattern solves; it's a different subject from this article's bug, not evidence that all derived values need memoizing.

Best practices: the actual test

Ask one question, in this order, every time a new value shows up in a component: could I compute this, right now, from props and state I already have?

Yes, and it's cheap → a plain const in the render body. No hook.
Yes, but it's measurably expensive → useMemo, still computed during render, still zero extra commits.
No, this value is genuinely new information from outside React (user input, a fetch response, a timer tick) → it's real state, and useEffect is the right tool if it also needs to synchronize with something outside React.
A prop change should reset an entire component's state → a key, not an Effect that calls several setStates in a row.

If you ever catch yourself writing a useEffect whose only job is calling setState with a value derived purely from props and other state already in scope, that Effect is the bug, not the fix.

FAQ

Is every `useState` that depends on props automatically derived state?

Not automatically — the test is whether the value is fully determined by props and other state, not whether it merely reads them. A text input's value reads a defaultValue prop once, then holds independent user edits; that's real state that happened to be seeded from a prop, not a formula recomputed from it every render.

Does using `useMemo` mean a value isn't derived state anymore?

No — useMemo is still deriving the value during render from the same inputs; it only caches the result between renders with unchanged inputs. A useMemo'd value and a plain const are the same kind of thing (a formula), differing only in whether the formula's cost justifies caching it.

Why does the Effect-based version actually visibly flash the wrong content?

Because Effects run after the browser has painted the render's output, not before it. The render with stale derived state is not skipped or invisible — it's a real commit the user can see, however briefly, before the Effect's setState triggers the corrected one.

Does the React Compiler make this whole article unnecessary?

No. The Compiler (stable at 1.0) automates memoizing values you already compute during render — it will not rewrite a useEffect-plus-setState pair into a derived calculation for you, because it can't safely know your Effect isn't also doing something with a real side effect. Removing the state is still a decision you make.

What's the actual bug, in one sentence, if I never fix this?

Two variables that are supposed to always agree occasionally won't, because one is memory and the other is a stale copy of a formula over that memory — and every real production codebase eventually hits the sequence of updates that makes them disagree.

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

Cheat sheet

Situation	What it is	What to write
Value fully computable from current props/state	Derived value	`const x = f(props, state)` — no hook
Same, but the computation is measurably slow	Derived value, cached	`useMemo(() => f(...), [deps])`
Genuinely new info from outside React (input, fetch, timer)	State	`useState`, updated by the event/callback that produced it
A prop change should reset a whole component's state	Identity change	`<Child key={propValue} />`
A prop change should reset only one field, rest must survive	Narrow adjustment	Compare a stored `previous` value during render — last resort, comment it
Object/array passed through Context that would otherwise churn	Derived value, cached for consumers	`useMemo` around the Provider's `value`

// The one-line test, every time you reach for useState:
// "Could I calculate this from props/state I already have?"
// Yes  -> const, or useMemo if it's expensive. No Effect.
// No   -> it's real state. useEffect only if it must sync with
//         something outside React (DOM, subscription, network).

Key takeaways

If a value can be computed from props and state you already have, it isn't state — it's a formula, and it belongs in the render body.
A useEffect that calls setState with a derived value costs a real extra render (Effects run after the commit) and creates two copies of one fact, which can drift.
useMemo caches a derived calculation for performance; it never changes what the calculation returns and never replaces the decision to remove unnecessary state in the first place.
When a prop change should reset a component's state entirely, use key, not an Effect — it's a single render, not two.
The React Compiler automates memoizing derived values; it does not and cannot decide for you that a state variable shouldn't have existed.

Back to that todo list

The fix for the opening bug was never a smarter Effect — it was noticing that visibleTodos had no information in it that todos and filter didn't already have. Delete the state, keep the formula, and the "complete all" bug and the one-paint flash both disappear, because there was never a second fact to get out of sync in the first place.

Next time you write useEffect(() => setSomething(...), [dep]), try the one-line test from this article before you commit it: could something just be a const? If yes, you've probably found a bug before your users did.

What's the strangest derived-state bug you've shipped — and how long did it take to notice? Drop it in the comments.

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

Thanks for reading! Let's stay connected:

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

Your Browser Is Rejecting Every Drop On Purpose

Parsa Jiravand — Sun, 20 Sep 2026 16:26:35 +0000

A teammate pings you: the drag-and-drop on the Kanban board doesn't work. You can pick a card up — it goes translucent, follows the cursor, everything looks right — but dropping it on a column does nothing. No error. No red text in the console. The card just snaps back like the drop never happened.

You open the code. The listener is right there:

dropzone.addEventListener("drop", (e) => {
  const id = e.dataTransfer.getData("text/plain");
  dropzone.appendChild(document.getElementById(id));
});

Right element. Right event name, spelled correctly. dataTransfer.setData was called in dragstart with the same key. By every reasonable check, this should work. It doesn't — and it isn't going to, no matter how long you stare at this exact function, because the bug isn't in it.

Guess before you scroll: the fix isn't in the drop handler at all. It's a handler that isn't there yet.

The obvious things you'd check first — and why they don't help

The instinct is to suspect draggable. Divs aren't draggable by default the way images and links are, so you add draggable="true" to the card. Now dragstart fires, the ghost image appears, everything about picking up the card works exactly as it should.

Dropping it still does nothing.

Next instinct: maybe dataTransfer needs a different MIME key, or setData/getData need to match more exactly. You double, triple check the strings. They already matched. That was never the problem either.

Here's the part that's easy to miss: the browser doesn't consider your dropzone a valid place to drop anything, and it never told you. Its default behavior for any element receiving a drag is to refuse the drop — the same way it refuses to run a submit button's default action once you call preventDefault() on the form's submit event, except inverted: here, doing nothing is the default, and you have to actively cancel it to unlock the alternative.

The one handler nobody adds because its name gives nothing away

The event that carries this default is dragover — the one that fires repeatedly while the dragged item hovers over your element, several times a second, for as long as the drag continues. It sounds like a bookkeeping event, the kind you'd only need for a hover highlight. It is actually the gate:

dropzone.addEventListener("dragover", (e) => {
  e.preventDefault(); // <-- this is the whole fix
  e.dataTransfer.dropEffect = "move";
});

Add that one handler — nothing fancier, no new logic in drop — and the exact same drop listener from before starts firing. The browser was checking, on every single dragover tick, whether something had canceled its "refuse this drop" default. Nothing had. So by the time the cursor was released, there was nothing to drop onto, and the drop event was simply never dispatched. Not swallowed, not caught somewhere — never sent at all.

Most tutorials also cancel dragenter's default alongside dragover's, and it's worth doing — it lets you flip a highlight class the instant the drag enters instead of waiting for the first dragover tick, and it papers over a few older-Safari quirks. But dragover is the one that's load-bearing. Cancel only dragenter and skip dragover, and you're back to the same silent nothing you started with.

The second landmine, right behind the first

Fix that, and a Kanban board's columns usually need a hover highlight — "you're currently over a valid drop zone" — added and removed as the drag moves. The naive version:

dropzone.addEventListener("dragenter", () => dropzone.classList.add("over"));
dropzone.addEventListener("dragleave", () => dropzone.classList.remove("over"));

This flickers if the drop zone has any child elements — a card, a label, an icon — because dragenter/dragleave fire per element, and they bubble. Move the cursor from the column onto a card sitting inside it, and the browser fires dragleave on the column (you left it for the card) immediately followed by dragenter on the card. Your highlight class turns off and back on, several times a second, every time the cursor crosses a child boundary. It isn't a bug in your logic — it's the DOM correctly reporting boundary crossings you didn't think to account for.

The fix is to stop trusting "did I leave" and check "did I leave into something outside this element," using the leave event's relatedTarget:

dropzone.addEventListener("dragleave", (e) => {
  if (!dropzone.contains(e.relatedTarget)) dropzone.classList.remove("over");
});

🎮 Try it yourself

▶️ Open the interactive playground →

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

The data you can't read yet, either

One more surprise waits for anyone who tries to log the dragged payload early, to debug the two problems above: call e.dataTransfer.getData("text/plain") inside dragover or dragenter, and you get back an empty string — even though dataTransfer.types correctly lists "text/plain" as available, and even though the exact same call works fine one line later, inside drop.

That's not a race condition and it's not something you configured. The drag data store runs in what the spec calls "protected mode" for the whole drag except the dragstart moment (when it's writable) and the drop moment (when it's finally readable) — a deliberate guard so that a page you're merely dragging over, which never receives the drop, can't read what you're carrying. If you need to know what's being dragged before the drop — to decide, say, whether this drop zone should even light up for this drag — read dataTransfer.types (always available) instead of the data itself.

Where this doesn't reach

All of this — dragstart, dragover, drop, the whole dataTransfer dance — is a mouse-and-desktop story. No major mobile browser fires these events for a finger drag; the touch input model and the HTML Drag and Drop spec were never wired together. If your Kanban board needs to be reorderable on a phone, this API isn't the one that gets you there — you're reaching for Pointer Events with your own hit-testing, or a library like SortableJS that's already done that work. Ship native drag-and-drop as a desktop enhancement, not the only way in.

The teammate's bug report wasn't wrong, and neither was their code. It was missing one handler whose entire job is invisible until you know to look for it — the browser was waiting, tick after tick, for a preventDefault() call that never came, and nothing about a missing drop event tells you that's what's missing.

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

Go check your own drop zones. If you've got a drop listener with no dragover listener next to it, it's not broken by accident — it's working exactly as specified, refusing every drop on purpose. What's the last time a "the listener's just not firing" bug turned out to be a default you needed to cancel somewhere else entirely?

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

Nuxt Hydration Mismatch: Why It Happens and How to Fix It

Parsa Jiravand — Sun, 20 Sep 2026 16:26:04 +0000

Your Nuxt page looks perfect. "View Source" shows clean, fully-rendered HTML — the hero text, the product price, the footer, all there before a single line of JavaScript ran. Then the client bundle finishes loading, and the console lights up: [Vue warn]: Hydration text mismatch. Sometimes it's cosmetic — a number flickers and settles. Sometimes it's worse: a button the user already clicked stops responding, because Vue just tore out the DOM node it was attached to and built a new one.

This is a hydration mismatch, and it's arguably the most Nuxt-specific bug you'll ever debug. It has nothing to do with your logic being wrong in the way a typo is wrong — your component can be perfectly correct JavaScript and still cause one, because the bug isn't in what you wrote, it's in the fact that Nuxt runs what you wrote twice, in two different places, and bets your app's interactivity on both runs agreeing.

This article is written against Nuxt 4.x (verified against the v4.5 release line, August 2026), using the Composition API, auto-imports, and the app/ directory convention Nuxt 4 defaults to. Everything here also applies to Nuxt 3's compatibilityVersion: 4 mode.

What you'll learn

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

Explain exactly what "hydration" means in Nuxt and why a mismatch happens
Recognize the handful of code patterns that reliably cause one
Pick the right fix — onMounted, <ClientOnly>, or data-allow-mismatch — for each situation
Read a hydration warning and know which line of your code to blame
Avoid the "fix" that looks reasonable but guarantees a mismatch every time

Who this is for

You've built at least one Nuxt page with <script setup> and know roughly what server-side rendering means (the server sends back real HTML instead of an empty <div id="app">). You don't need prior SSR debugging experience — that's the point of this article.

The problem: a page that's "correct" and still breaks
The mental model: two renders, one DOM
Fixing it, stage by stage
Edge cases and gotchas
Best practices
FAQ
Cheat sheet
Key takeaways

The problem: a page that's "correct" and still breaks

Say you're building a "tip of the day" widget. It's a plain computed value, no fetch, no state management — about as simple as a Vue component gets:

<script setup>
const TIPS = [
  "Use useAsyncData for anything that fetches.",
  "Auto-imports save you the import line, not the thinking.",
  "Nitro is just Node under the hood.",
]

const tip = TIPS[Math.floor(Math.random() * TIPS.length)]
</script>

<template>
  <p>Tip of the day: {{ tip }}</p>
</template>

Nothing here looks wrong. It compiles, it runs, npm run dev shows a tip. But open the browser console and you'll see something like:

[Vue warn]: Hydration text mismatch:
- Server rendered:  Tip of the day: Nitro is just Node under the hood.
- Client rendered:  Tip of the day: Use useAsyncData for anything that fetches.

Nothing crashed. The page still works. But the text the user saw for a split second — the one baked into the HTML the server sent — silently got replaced by a different one the instant the JavaScript took over. If that "tip" were a price, a username, or which item was in stock, this wouldn't be a curiosity, it would be a bug report.

The same failure mode shows up with new Date(), with window.innerWidth, with anything read from localStorage inside the component's render path. The common thread: the value depends on where the code runs, and Nuxt runs your component in two different places.

The mental model: two renders, one DOM

The mental model: Nuxt doesn't render your app once — it renders the same component tree twice, in two different environments, and then asks the second render to adopt the DOM the first render already produced, instead of rebuilding it from scratch.

Here's the sequence for a single page request:

A request hits your server. Nitro runs your Vue app in Node — no browser, no DOM — and walks your components to produce a plain HTML string, plus a serialized payload: the results of every useAsyncData/useFetch call and every useState, embedded in the page as a <script id="__NUXT_DATA__"> block.
The browser receives that HTML and paints it immediately. This is the entire point of SSR — the user sees real content before a single byte of your JavaScript bundle has downloaded.
The client bundle downloads and boots the same Vue app, client-side. But instead of creating new DOM nodes the way a client-only SPA would, it runs in hydration mode: it walks the existing DOM the server produced, node by node, and attaches reactivity and event listeners to what's already there, reading the payload from step 1 so it doesn't have to re-fetch data the server already fetched.

Hydration is a reconciliation, not a second render from scratch — and reconciliation assumes the two renders agree. When they do, hydration is invisible: the DOM stays exactly as the server drew it, listeners attach, the page becomes interactive. When they don't, Vue has two options depending on how badly they disagree:

A text or attribute mismatch (a {{ tip }} that resolved differently, a class that differs): Vue patches just that value in place and — in development only — logs a warning. Production builds do this silently, which is why a mismatch can ship for weeks before anyone notices.
A structural mismatch (a different tag, a different number of children — the kind you get from v-if branching differently on each side): Vue can't patch that in place. It throws away the mismatched subtree and re-renders it entirely client-side. That's real, visible re-work, and if a user had already interacted with something inside that subtree, the element they clicked no longer exists.

The payload exists specifically so that data is safe across hydration — useAsyncData, useFetch, and useState all serialize their results, so the client reads the exact value the server used instead of recomputing it. (If you've read the earlier episode on useAsyncData keys and dedupe, this is the same payload that makes dedupe possible — it's doing double duty.) The danger is everything outside that mechanism: any value your template reads that isn't backed by useState/useAsyncData and isn't guaranteed identical on both sides — Math.random(), Date.now(), window, navigator, localStorage — is a mismatch waiting to happen, because nothing carries it across the server→client boundary for you.

Fixing it, stage by stage

Stage 1: defer the value with `onMounted`

The tip-of-the-day bug and the "current time" bug are the same shape: a value that's legitimately allowed to differ per visitor, rendered directly during setup. The fix is to give the template a stable, server-safe default, and only fill in the real value once you're certain you're client-side:

<script setup>
import { ref, onMounted } from "vue"

const tip = ref(null)

onMounted(() => {
  const TIPS = ["Use useAsyncData for anything that fetches.", "…"]
  tip.value = TIPS[Math.floor(Math.random() * TIPS.length)]
})
</script>

<template>
  <p>Tip of the day: {{ tip ?? "Loading…" }}</p>
</template>

Key concept: onMounted runs only after hydration has already completed successfully. Anything it writes is a normal, client-only reactive update — Vue never has to reconcile it against server HTML, because by the time it runs, hydration is already done.

Stage 2: skip SSR entirely with `<ClientOnly>`

Some content isn't "slightly different" between server and client — it can't exist on the server at all. A chart that measures its container's pixel width, a widget that reads localStorage, a third-party embed that expects window. For those, don't try to make the server render something — tell Nuxt not to render it there in the first place. <ClientOnly> is auto-imported and does exactly that:

<template>
  <ClientOnly>
    <UserLocalClock />
    <template #fallback>
      <span class="clock-placeholder">--:--</span>
    </template>
  </ClientOnly>
</template>

The default slot never runs on the server. The #fallback slot renders there instead (useful for reserving layout space so nothing jumps), and the moment the component mounts client-side, Nuxt swaps the fallback for the real content — created fresh, never hydrated.

Key concept: <ClientOnly> doesn't resolve a mismatch — it removes the possibility of one, because nothing inside it is ever compared between two renders. There's only ever one render, on the client.

Stage 3: the branch that looks like a fix but isn't

It's tempting to reach for Nuxt's environment flags — import.meta.server / import.meta.client (the modern replacement for the older process.server / process.client) — and branch your template directly on them:

<!-- Don't do this -->
<template>
  <div v-if="import.meta.client">Client-rendered content</div>
  <div v-else>Server-rendered content</div>
</template>

This guarantees a structural mismatch, every single time. On the server, import.meta.server is true, so the server emits the <div> from the v-else branch. On the client, during hydration, import.meta.client is true, so Vue's hydration walk expects the v-if branch — a different <div> than the one actually sitting in the DOM. Vue can't reconcile two different branches in place; it discards and re-renders. import.meta.client/.server are genuinely useful for deciding what code runs (skip a browser-only import on the server, skip a Node-only one on the client) — they're the wrong tool for deciding what a hydrated template renders, because that decision has to be identical in both places by definition.

Stage 4: when a mismatch is real, expected, and fine — `data-allow-mismatch`

Occasionally you'll have a value that will always differ by design — a relative timestamp ("posted 3 minutes ago") that keeps ticking, for instance — and you've already accepted that as correct behavior rather than a bug. Vue 3.5 added an attribute for exactly this: data-allow-mismatch silences the hydration warning for a specific element, scoped to the kind of mismatch you name (text, children, class, style, or attribute):

<time data-allow-mismatch="text">{{ relativeTime }}</time>

This only suppresses the console warning — it does nothing to make the values agree. Reach for it after you've decided the mismatch is cosmetic and harmless, never as a first response to a warning you haven't diagnosed yet.

Edge cases and gotchas

Invalid HTML nesting causes mismatches with no logic bug at all. A <div> nested inside a <p>, or malformed <table> markup, gets silently corrected by the browser's HTML parser while it parses the server's HTML — the browser closes the <p> early, restructuring the tree Vue expected to hydrate onto. The fix is markup hygiene, not JavaScript: keep nesting valid per the HTML content model.
Browser extensions mutate the DOM before your JS runs. Grammarly, password managers, and dark-mode extensions routinely inject attributes into the page before hydration starts. These aren't your bug and can't be reliably prevented; data-allow-mismatch="attribute" on the affected element is the pragmatic escape valve once you've confirmed the source.
Server and client timezones differ. A server running in UTC formatting a date directly in a template will disagree with a client in the visitor's local timezone. Same class of bug as Date.now() — same fix: compute the display string in onMounted.
A ref seeded from a browser API at module or setup scope. const isWide = ref(window.innerWidth > 768) throws on the server (there is no window) or, if guarded, still needs a server-safe default and a client-side correction — the same onMounted pattern applies.
Shared server state is a related but different bug. If your mismatch is about the wrong user's data appearing rather than a timing difference, that's the cross-request state leak, not a hydration mismatch — see the earlier episode on useState vs. a plain ref if that's the symptom you're chasing.

Best practices

Ask one question of every render-affecting expression: given the same props and payload, does this produce the exact same output on the server and the client? If the honest answer is "no," it doesn't belong directly in the template.
Default first, correct in onMounted. Any value that's allowed to differ per visitor gets a server-safe placeholder and a client-side update after mount — never a direct read of a browser API during setup.
Reach for <ClientOnly> for whole widgets, not individual values. If an entire component only makes sense in a browser (canvas-sized charts, window-dependent libraries), don't fight it into an SSR-safe shape — skip SSR for it.
Never branch a hydrated template's markup on import.meta.client/.server. Use those flags to decide what code runs, not what a hydrated component renders.
Lint your markup. Invalid HTML nesting is an easy, boring source of mismatches that a markup or accessibility linter catches before it ever reaches a browser.
Test against a production build, not just nuxt dev. Run nuxt build && nuxt preview before shipping something that touches SSR — dev's warnings are the same, but dev's timing can mask issues that show up under real hydration.

FAQ

Does a hydration mismatch crash my app?

No — Vue reconciles it either way. A text/attribute mismatch is patched in place; a structural one is discarded and re-rendered client-side. The app keeps working, but a structural mismatch means real extra work and a possible flash or loss of state in that subtree.

Why does the warning only appear in development?

Vue's hydration mismatch console warning is a development-only diagnostic. In a production build, the same reconciliation happens, but silently — which is exactly why these bugs can ship unnoticed for a long time. Always sanity-check SSR-sensitive pages against a nuxt preview build, not just dev.

Is `<ClientOnly>` the same thing as checking `import.meta.client`?

No. import.meta.client is a compile-time flag that decides which lines of code are included in which bundle — it's a build-time tool. <ClientOnly> is a runtime component that skips server rendering for its slot content and mounts it fresh in the browser. Using the flag to branch a hydrated template's markup causes the exact mismatch this article is about; <ClientOnly> avoids it by never hydrating that content at all.

Does `useState` prevent hydration mismatches?

It prevents the specific class caused by state disagreeing between server and client, because its value is serialized into the payload and read identically on both sides. It doesn't protect a value your template computes independently of useState — Math.random() inside a <script setup> block is still a mismatch even if an unrelated useState call exists elsewhere in the same component.

Can a mismatch happen even when my code is completely correct?

Yes. Third-party scripts and browser extensions can alter the DOM before your app hydrates, and that's outside your code's control. data-allow-mismatch on the specific affected attribute is the accepted mitigation once you've confirmed that's the cause.

Cheat sheet

Situation	Symptom	Fix
`Math.random()` / `Date.now()` read during setup or render	Text mismatch warning, value flickers on load	Default to `null`/placeholder, set the real value in `onMounted`
Reading `window`, `navigator`, `localStorage` in the template's data path	Throws on server, or mismatches if guarded naively	`ref(defaultValue)` + `onMounted` to correct it
Whole widget only makes sense client-side (canvas size, browser-only lib)	Mismatch or server crash	Wrap it in `<ClientOnly>` with a `#fallback`
`v-if="import.meta.client"` branching a hydrated template	Structural mismatch, guaranteed, every load	Don't branch markup on the flag — use `<ClientOnly>`/`onMounted` instead
Relative time / genuinely-expected drift you've accepted	Warning you don't want to see	`data-allow-mismatch="text"` (Vue 3.5+) — after you've confirmed it's harmless
`<div>` inside `<p>`, broken table markup	Mismatch with no obvious cause in your JS	Fix the HTML nesting; lint markup
Grammarly / extensions injecting attributes	Attribute mismatch you can't reproduce locally without the extension	`data-allow-mismatch="attribute"` on the affected element

<script setup>
import { ref, onMounted } from "vue"

// Server-safe default — identical on both renders.
const clientValue = ref(null)

onMounted(() => {
  // Runs only after hydration succeeds — safe to diverge here.
  clientValue.value = computeSomethingClientOnly()
})
</script>

<template>
  <p>{{ clientValue ?? "Loading…" }}</p>

  <!-- For whole subtrees that can never run on the server: -->
  <ClientOnly>
    <BrowserOnlyWidget />
    <template #fallback><span>Loading…</span></template>
  </ClientOnly>
</template>

🎮 Try it yourself

▶️ Open the interactive playground →

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

Key takeaways

A hydration mismatch happens because Nuxt renders your app twice — once on the server, once in the browser — and hydration assumes, without verifying up front, that both renders agree.
The near-universal cause is a render-affecting value that isn't guaranteed identical on both sides: Math.random(), Date.now(), or any direct read of a browser-only API.
onMounted fixes values that are allowed to differ once hydration is already done; <ClientOnly> fixes whole subtrees that can never run on the server; data-allow-mismatch only silences a warning you've already confirmed is harmless.
Never branch a hydrated template's markup on import.meta.client/.server — that's the one "fix" that reliably causes the exact bug it's trying to solve.

🧠 Test yourself

Think it clicked? Take the 9-question quiz →

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

One more render to get right

That tip-of-the-day widget from the top of this article has an honest fix now — a ref that starts null and fills in after mount, instead of a Math.random() call sitting directly in the render path. The bug was never really about randomness; it was about where the randomness ran, and Nuxt was always going to run it twice.

What's the strangest hydration mismatch you've had to track down — a third-party script, a timezone, something stranger? Drop it in the comments; there's a decent chance someone else's next [Vue warn] is exactly the one you already solved.

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

Thanks for reading! Let's stay connected:

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

DEV Community: Parsa Jiravand

getCurrentPosition() Doesn't Just Check — It Prompts

There's no "just checking" with the Geolocation API

The API that only reads

The catch: not every browser recognizes every name

The lesson

🎮 Try it yourself

🧠 Test yourself

NestJS Guards: CanActivate, ExecutionContext & Reflector

What you'll learn

Who this is for

Table of contents

The problem: a guard that quietly can't do its job

The mental model: a guard is a provider, not a function

Stage 1: the smallest correct guard

Stage 2: ExecutionContext, properly

Stage 3: Reflector and a real @Roles() decorator

Stage 4: registering a global guard without losing DI

Stage 5: composing guards — order and "all must pass"

Edge cases and gotchas

Best practices

FAQ

Do guards run before or after middleware?

Can a guard inject a service?

Can I use @UseGuards() more than once on the same controller?

What does a guard returning false actually send to the client?

Is Reflector only for guards?

Cheat sheet

Key takeaways

Ending

🎮 Try it yourself

🧠 Test yourself

localStorage Isn't Free — It's Blocking Your Main Thread

The obvious fix that doesn't fix it

What's actually blocking

The fix: an API that doesn't block

🎮 Try it yourself

The lesson

🧠 Test yourself

JSON.stringify Is Quietly Deleting Your File Uploads

The code that looks completely fine

What Object.fromEntries actually hands you

The "fix" that makes it worse

The actual fix: stop converting to JSON

One more thing Object.fromEntries was hiding

🎮 Try it yourself

The lesson

🧠 Test yourself

The Background Task That Waited 40 Seconds for 'Idle'

What you probably think it does

Idle time isn't a clock. It's a gap.

🎮 Try it yourself

The timeout option doesn't fix this — it changes what breaks

It isn't Baseline — and the polyfill people write is a footgun

Not the same job as scheduler.yield

The fix for the draft that didn't save

🧠 Test yourself

The takeaway

Vue Composables: The Shared State Trap (+ Cheat Sheet)

What you'll learn

Who this is for

Table of contents

The problem: two counters, one number

The mental model: a composable is just a function

Stage 1: state that lives inside the function

Stage 2: composables with side effects need cleanup

Stage 3: composables that call other composables

Stage 4: when shared state is what you actually want

Edge cases and gotchas

Best practices

FAQ

Why didn't Vue warn me that my composable's state was shared?

Does this affect provide/inject the same way?

Is a composable just a React-style custom hook?

Should every composable clean up after itself, even ones that don't touch the DOM?

Can I tell from the outside whether a composable shares state?

🎮 Try it yourself

Cheat sheet

Key takeaways

🧠 Test yourself

Stage 3: Reflector and a real `@Roles()` decorator

Can I use `@UseGuards()` more than once on the same controller?

What does a guard returning `false` actually send to the client?

Is `Reflector` only for guards?

What `Object.fromEntries` actually hands you

One more thing `Object.fromEntries` was hiding

Not the same job as `scheduler.yield`

Does this affect `provide`/`inject` the same way?

Is `proxy.ts` a completely new file, or a rename?

Can I run `proxy.ts` on the Edge runtime if I really want to?

What `100vh` actually measures

Is every `useState` that depends on props automatically derived state?

Does using `useMemo` mean a value isn't derived state anymore?