DEV Community: Parsa Jiravand

React 19.2 useEffectEvent: Why It Won't Fix Your Deps Array

Parsa Jiravand — Sat, 17 Oct 2026 12:20:56 +0000

Your chat room component reconnects every time someone flips the dark-mode switch. Messages in flight get dropped, the "typing…" indicator resets, and support tickets call it "random." The bug isn't the dark-mode toggle — it's that theme is sitting in a useEffect dependency array next to roomId, and React has no way to know that only one of those two values should actually restart the connection.

The reflex fix — deleting theme from the array and silencing the lint warning — trades one bug for a worse one: the notification that fires on connect now shows whatever theme was active the moment the connection opened, forever, no matter how many times the user flips the switch afterward. That's a stale closure, and it's the single most common useEffect bug there is.

React 19.2 (released October 1, 2025) shipped a real fix: the useEffectEvent Hook. It lets an Effect read a value's current state without that value forcing the Effect to re-run — something no combination of dependency-array tricks could do safely before. This article covers what useEffectEvent actually does, the exact rules for using it, and the one way people keep misusing it that makes things worse, not better.

This article is written against React 19.2+ / 19.3.0 (verified against the current npm latest dist-tag for react and cross-checked coverage of the official 19.2 release notes and the React docs' "Separating Events from Effects" guide; react.dev itself was unreachable from this run's network, so claims here lean on the npm registry plus multiple independent write-ups of the same release). useEffectEvent requires React 19.2 or later and assumes React 19-era function components and hooks throughout.

What you'll learn

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

Explain the real difference between a value an Effect must depend on and a value an Effect only needs to read the latest copy of
Reproduce the stale-closure bug that "just remove it from the deps array" causes, and name why it happens
Extract non-reactive logic out of an Effect with useEffectEvent and call it correctly
List the hard rules — where it can be called, what it can't be passed to, why it's excluded from the dependency array — and what breaks if you ignore them
Recognize when useEffectEvent is the wrong tool, because the value genuinely should resynchronize the Effect

Who this is for

You've written a useEffect with a dependency array, you've seen the react-hooks/exhaustive-deps lint warning, and you've been tempted to either silence it or just add everything it asks for. No class components or Server Components knowledge required.

The problem: one dependency array, two different jobs
The mental model: reactive values vs. Effect Events
Stage 1 — the naive fix and its stale closure
Stage 2 — useEffectEvent, correctly
Stage 3 — more than one Effect Event
Edge cases and gotchas
Best practices
FAQ
Cheat sheet
Key takeaways

The problem: one dependency array, two different jobs

Here's the chat room, written the obvious way:

function ChatRoom({ roomId, theme }) {
  useEffect(() => {
    const connection = createConnection(roomId);
    connection.on("connected", () => {
      showNotification("Connected!", theme);
    });
    connection.connect();
    return () => connection.disconnect();
  }, [roomId, theme]);

  return <h1>Welcome to {roomId}</h1>;
}

react-hooks/exhaustive-deps is doing its job here: the Effect reads both roomId and theme, so both are listed. The code is "correct" by the lint rule's own standard. It's also wrong in a way the lint rule has no way to catch, because the rule only knows one move — list everything you read — and that move doesn't distinguish between two genuinely different jobs a value can have inside an Effect:

roomId decides what the Effect does. A different room means a different connection. If roomId changes and the Effect doesn't re-run, you're connected to the wrong room. This is a reactive value — the Effect's whole reason for existing is synchronized to it.
theme is only read once the connection is already open, to decide what the notification looks like. It has no bearing on which room you connect to. Listing it as a dependency doesn't make the code more correct — it makes the Effect re-run (disconnect, then reconnect) for a reason that has nothing to do with what the Effect is for.

Toggle dark mode in this version and the user drops their connection. Not because anything about the connection needed to change — because the lint rule, correctly, cannot tell the difference between "this value controls what the Effect synchronizes with" and "this value is read once a thing the Effect already started happens to fire."

The mental model: reactive values vs. Effect Events

The mental model: a useEffect dependency array isn't a list of "everything this function touches" — it's a list of reactive values the Effect's job depends on. If a value changing should legitimately restart what the Effect is doing, it belongs in the array, full stop; that's not a style choice, it's correctness. But some reads inside an Effect aren't about what the Effect is doing at all — they're about what to do when something the Effect already set up happens later. React 19.2 gives that second category a name — an Effect Event — and a Hook to create one: useEffectEvent.

An Effect Event is a function, declared with useEffectEvent(fn), whose body is deliberately non-reactive: every time your component re-renders, React relinks the function to that render's latest props and state, but the function itself is never a dependency and never forces anything to re-run. You call it from inside an Effect (or from inside another Effect Event) when the thing it does should happen using whatever is current right now, not whatever was current when the Effect last ran.

Put plainly: roomId answers "what should this Effect be connected to?" — that's reactive, and it belongs in the array. theme answers "what should happen, using today's value, when the thing I already connected to does something?" — that's an Effect Event, and it has no business in the array at all.

Stage 1 — the naive fix and its stale closure

Before useEffectEvent existed, the common workaround was to simply drop theme from the array and disable the lint rule:

function ChatRoom({ roomId, theme }) {
  useEffect(() => {
    const connection = createConnection(roomId);
    connection.on("connected", () => {
      // theme is captured from THIS render, forever, until roomId changes again
      showNotification("Connected!", theme);
    });
    connection.connect();
    return () => connection.disconnect();
    // eslint-disable-next-line react-hooks/exhaustive-deps -- intentionally wrong, see below
  }, [roomId]);

  return <h1>Welcome to {roomId}</h1>;
}

This stops the reconnect. It also freezes theme at whatever it was the moment the Effect last ran. JavaScript closures capture variables by reference to the scope they were created in, not by re-reading them later — so the theme inside connection.on("connected", …) is the one value from the render that created this particular closure. Flip dark mode ten times after that; the notification keeps showing the old theme until roomId changes and the whole Effect reruns. That's the stale closure: the code looks like it reads theme, but it's reading a frozen copy from the past.

This is the trap of "just remove it from the deps array and silence the warning": you've fixed the symptom (unwanted reconnects) by reintroducing the exact class of bug the lint rule exists to prevent (stale reads), just somewhere the rule can no longer see it.

Stage 2 — useEffectEvent, correctly

useEffectEvent splits the two jobs apart explicitly instead of hiding one of them:

import { useEffect, useEffectEvent } from "react";

function ChatRoom({ roomId, theme }) {
  const onConnected = useEffectEvent(() => {
    // Always reads the CURRENT theme, no matter when this runs.
    showNotification("Connected!", theme);
  });

  useEffect(() => {
    const connection = createConnection(roomId);
    connection.on("connected", () => onConnected());
    connection.connect();
    return () => connection.disconnect();
  }, [roomId]); // only roomId — and this time that's actually correct, not a lie

  return <h1>Welcome to {roomId}</h1>;
}

Key concept: onConnected is recreated on every render like any other local function, but calling it never reads a frozen snapshot — React always runs it against the component's latest props and state. Its identity is deliberately not stable across renders (unlike a useState setter or a useCallback-memoized function) — that's by design, so nothing can accidentally rely on it staying the same or pass it around like a normal callback. It simply can never legally appear in the dependency array in the first place, so the instability never causes a re-run. The Effect's dependency array now says something true: this Effect only needs to re-run when roomId changes. theme can change a thousand times without touching the connection, and the notification will still report whatever theme is active the instant it fires.

Toggle dark mode now: no disconnect, no reconnect, and the next notification shows the theme you just switched to. Both halves of the original bug — unwanted reconnects and stale reads — are gone, because they were never actually the same problem. They were two different values wearing one dependency array.

🎮 Try it yourself

▶️ Open the interactive playground →

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

Stage 3 — more than one Effect Event

The pattern scales past a single notification. Say the chat room also has a mute toggle that should silence a "ping" sound without, again, reconnecting:

function ChatRoom({ roomId, theme, isMuted }) {
  const onConnected = useEffectEvent(() => {
    showNotification("Connected!", theme);
  });

  const onMessage = useEffectEvent((message) => {
    if (!isMuted) playSound();
    logMessage(message, theme);
  });

  useEffect(() => {
    const connection = createConnection(roomId);
    connection.on("connected", () => onConnected());
    connection.on("message", (msg) => onMessage(msg));
    connection.connect();
    return () => connection.disconnect();
  }, [roomId]); // roomId is the only reactive value here

  return <h1>Welcome to {roomId}</h1>;
}

Key concept: theme and isMuted can each change independently, as often as the user likes, and neither one is a dependency anywhere. The rule that decides what goes in useEffect's array hasn't changed — list every reactive value the Effect's behavior depends on — it's just that theme and isMuted were never one of those to begin with. They were Effect Event inputs all along; useEffectEvent just gives that distinction a real API instead of a lint-rule workaround.

Edge cases and gotchas

You can only call an Effect Event from inside an Effect, or from inside another Effect Event. Calling it during render, or handing it to a child component or another Hook as a prop, is not supported — eslint-plugin-react-hooks (6.1 and later; the current major is 7.x) flags both.
It must be declared at the top level of a component or custom Hook, like any other Hook — not inside a loop, condition, or nested function. If you need one per item in a list, pull that item into its own component.
It cannot go in a dependency array. You don't need to add it — the lint rule never asks you to — and if you add it anyway, a current eslint-plugin-react-hooks flags it directly (Functions returned from useEffectEvent must not be included in the dependency array) and tells you to remove it, because the whole point is that it isn't reactive.
It is not a blanket fix for exhaustive-deps warnings. If a value genuinely should restart the Effect — roomId in every example above — wrapping it in useEffectEvent to make the warning go away reintroduces the exact stale-closure bug Stage 1 showed, just with a newer API wrapped around it. The question to ask every time is "should this value actually restart what the Effect is doing?", not "how do I make the warning stop."
It doesn't replace useRef for everything. If you need to read a value from outside any Effect at all — say, inside a setTimeout callback registered by an event handler, not an Effect — useEffectEvent's restriction to Effects means a ref, or a plain callback prop, is still the right tool.
Server Components never run Effects, so this is purely a client-component concern; it doesn't change anything about the server/client boundary.

Best practices

Reach for useEffectEvent when an Effect's trigger condition should stay narrow (one connection per roomId) but an action it fires needs to use whatever is current at the moment it fires, not whatever was current when the Effect last started.
Don't reach for it reflexively every time exhaustive-deps complains. First ask whether the flagged value should actually resynchronize the Effect. If yes, keep it in the array — that's not friction, that's the rule doing its job.
Keep Effect Events small and named for what they do (onConnected, onMessage), not for what they avoid (stableTheme). The name should describe the moment it fires, because that's the mental model you're encoding.
Pair it with a real connection/subscription pattern, not a one-off side effect. The value of splitting reactive setup from non-reactive reaction shows up most in Effects that stay alive across renders — connections, subscriptions, timers — not in an Effect that runs once and is done.

FAQ

Is `useEffectEvent` a replacement for `useCallback`?

No. useCallback memoizes a function's identity across renders so a child doesn't re-render or a dependency array doesn't see a "new" function every time. useEffectEvent doesn't memoize for performance — it changes what the function is allowed to see (always-latest, never-reactive) and where it can be called from (only Effects and other Effect Events). They solve different problems and aren't interchangeable.

Can I call an Effect Event from a click handler?

No — an Effect Event can only be called from inside an Effect or another Effect Event, and the lint rule enforces this. If you need current-value behavior inside an onClick, you already have it: a normal event handler always closes over the latest render's values naturally, because it's recreated every render. The stale-closure problem this Hook solves is specific to long-lived Effects, not short-lived event handlers.

Did this exist before React 19.2?

Yes, behind an unstable name. It shipped for a long stretch as experimental_useEffectEvent, and the stabilized, unprefixed useEffectEvent landed in React 19.2 (October 2025). Code written against the experimental name needs the import updated, but the behavior and rules carried over.

Does `useEffectEvent` need a special ESLint setup?

You need a current eslint-plugin-react-hooks (6.1+; 7.x as of this writing) for the linter to correctly exclude Effect Event functions from dependency-array warnings instead of flagging them as missing. Without it, you'll fight the linter over something it already knows how to handle in a current version.

What happens if I put the Effect Event function in the dependency array anyway?

A current eslint-plugin-react-hooks flags it and tells you to remove it — it won't silently let it through. Functionally, adding it wouldn't do anything useful even if the linter allowed it: the function reference itself isn't what makes the behavior reactive or not. The reactivity question was never about the Effect Event's identity; it's about the values inside it, which are intentionally not tracked.

Cheat sheet

Situation	What to do	Why
A value decides what the Effect connects to / sets up	Keep it in the dependency array	It's reactive — the Effect's job changes when it changes
A value is only read after something the Effect set up fires	Read it inside a `useEffectEvent`	Always current, never forces a re-run
Tempted to silence `exhaustive-deps` by deleting a dependency	Ask: should this value restart the Effect? If yes, keep it. If no, wrap the code that reads it in `useEffectEvent`	Deleting it silently reintroduces a stale closure
Need current-value behavior inside an `onClick`/`onChange`	Do nothing special	Event handlers already close over the latest render
Need current-value behavior inside a `setTimeout` set up outside any Effect	Use a ref	`useEffectEvent` only works from inside Effects

import { useEffect, useEffectEvent } from "react";

function ChatRoom({ roomId, theme, isMuted }) {
  // Non-reactive reads live here — never in the deps array, never the trigger.
  const onConnected = useEffectEvent(() => {
    showNotification("Connected!", theme);
  });

  useEffect(() => {
    // Only truly reactive values live here.
    const connection = createConnection(roomId);
    connection.on("connected", () => onConnected());
    connection.connect();
    return () => connection.disconnect();
  }, [roomId]);

  return <h1>Welcome to {roomId}</h1>;
}

Key takeaways

A useEffect dependency array lists reactive values the Effect's job depends on — not every value the Effect's body happens to read.
Deleting a value from the array to stop an unwanted re-run reintroduces a stale closure: the deleted value gets frozen at whatever it was when the Effect last ran.
useEffectEvent (stable since React 19.2, October 2025) gives non-reactive reads a real home: the function always sees the latest props/state, but it's never a dependency and never retriggers the Effect.
It can only be called from inside an Effect or another Effect Event — never during render, never passed to a child or another Hook.
It is not a workaround for exhaustive-deps — if a value should genuinely resynchronize the Effect, it still belongs in the array.

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

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

That chat room from the opening scene now reconnects exactly when it should — when the room changes — and never when someone just prefers a darker screen. The bug was never really about dark mode; it was two different questions hiding inside one dependency array, and useEffectEvent is what finally lets you answer them separately.

If React Derived State taught you that an Effect syncing one piece of state into another is usually a bug, this is the companion lesson for the Effects you do need: not every value they read is there for the same reason, and now there's a real API for telling them apart. And if Re-render vs Remount taught you that key decides which component instance you're looking at, the same instinct applies here — roomId decides which connection you're looking at, and theme never should have.

Have you shipped a stale-closure bug from an Effect's dependency array — did you find it from a bug report, or from reading the code? Tell me below.

📚 Read next

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

Thanks for reading! Let's stay connected:

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

Inferred Type Predicates Won't Save filter(Boolean). Here's What Will.

Parsa Jiravand — Sat, 17 Oct 2026 12:17:17 +0000

Open any "what's new in TypeScript 5.5" roundup from the last two years and you'll find some version of the same line: inferred type predicates finally fixed .filter(Boolean). It gets repeated because it's satisfying — a years-old annoyance, solved for free, no code changes needed. It also isn't true.

The feature that's actually in 5.5 is narrower than the myth, and more useful once you see what it's really for. You've probably been deleting type guards you didn't need to delete, right next to a .filter(Boolean) that's just as untyped as it was in 2019.

The claim, and why it's believable

Here's the example every one of those roundups leads with. Before TypeScript 5.5, this didn't narrow:

const maybeNumbers = [1, null, 2, null, 3];

// previously: (number | null)[] — TypeScript didn't trust the callback
const numbers = maybeNumbers.filter((n) => n !== null);

You wrote a callback that obviously removes null, ran it, and TypeScript still handed you back (number | null)[]. The only way to get a real number[] was to spell it out by hand:

const numbers = maybeNumbers.filter(
  (n): n is number => n !== null
);

That (n): n is number => syntax is a type predicate — a little promise to the compiler that says "if this returns true, treat the input as this narrower type." Writing it by hand, every time, for a check this obvious, was the exact kind of busywork TypeScript is supposed to save you from. TypeScript 5.5 fixed it: the plain (n) => n !== null now gets the predicate inferred automatically. No annotation. Same code, better type.

So far, every word of the popular claim checks out. Here's where it quietly goes off the rails.

Try the one line everyone actually writes

Nobody filters nulls with n !== null in real code nearly as often as they reach for the shorthand:

const configs = [getConfig(), null, getConfig(), undefined];

// still (Config | null | undefined)[] in every TypeScript version as of this writing
const valid = configs.filter(Boolean);

Paste that into the TypeScript playground. The result is still (Config | null | undefined)[] — the exact array you started with, falsy values and all. The feature that rewrote n !== null into a type guard does nothing here, on the single most common one-liner for exactly this job.

Quick gut check before you scroll: what's different between (n) => n !== null and Boolean, if they do the same job?

Why the compiler can see one and not the other

Inferred type predicates work by TypeScript reading a function's body and recognizing a pattern: one return statement, no implicit fall-through, the parameter isn't reassigned, and the thing being returned is a boolean check tied directly to that parameter. (n) => n !== null qualifies on every count — it's a tiny, transparent function, and the compiler can see exactly what it decides and why.

Boolean isn't a function you wrote. It's the global constructor, declared in TypeScript's own standard library as a call signature with no visible implementation — (value?: any) => boolean, full stop. There's no body for the inference engine to read, because as far as the type checker is concerned, there's no body at all. It's an ambient declaration, same category as parseInt or Array.isArray: TypeScript trusts the signature you gave it and nothing more. Teaching the compiler to special-case .filter(Boolean) specifically would mean hard-coding one function name into the type checker — not inference, a workaround with a name attached.

That's the actual boundary of the 5.5 feature: it infers predicates from code it can read. Boolean was never going to be included, in 5.5 or any release after it, unless the standard library itself grows a dedicated overload for it — which, as of this writing, it hasn't.

🎮 Try it yourself

▶️ Open the interactive playground →

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

Why the mix-up happened

Nobody misreported this out of carelessness. .filter(n => n !== null) and .filter(Boolean) solve the identical problem and read, to a human, like two spellings of the same idea. The release notes' headline example uses the first form because it's the clean one to explain in a changelog. Readers who've spent years typing the second form saw "filter now narrows" and reasonably assumed their own habit was covered.

It's the kind of gap that only shows up when you actually run the code, which most roundups — understandably, on a deadline — don't.

What to actually do with your type guards

The real payoff of 5.5 is that you can delete annotations you were writing by hand, as long as the function itself is one TypeScript can read:

// before 5.5 — had to spell out the predicate yourself
function isDefined<T>(value: T): value is NonNullable<T> {
  return value != null;
}

// 5.5+ — this now infers the exact same predicate, with no `is` anywhere
function isDefined<T>(value: T) {
  return value != null;
}

const valid = configs.filter(isDefined); // Config[] — for real this time

That's a genuine win: a helper function you've probably had in a utils.ts file for years just got shorter, and any arrow function shaped like it gets the same treatment for free. What it isn't is a reason to rip out isDefined and go back to .filter(Boolean) for brevity — that one line is exactly where the narrowing still doesn't reach. If you want the one-liner and the types, write the predicate yourself:

const valid = configs.filter(
  (c): c is NonNullable<typeof c> => Boolean(c)
);

Same runtime behavior as .filter(Boolean), three extra words, and an array type you can actually trust downstream.

The takeaway

TypeScript 5.5 didn't make filter(Boolean) type-safe — it made your own boolean-returning functions smart enough that you stop writing is annotations for them by hand. Keep the named helper, drop its predicate syntax, and reach for the explicit inline predicate only when you actually want the Boolean-style one-liner. The compiler was never going to read minds; it just got better at reading your functions.

Next time a changelog claims a one-line fix for a years-old annoyance, paste the actual snippet into the playground before you repeat it. What's one you've seen repeated that didn't hold up?

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

Stop Letting One Widget Reflow the Whole Page. `contain` Scopes It.

Parsa Jiravand — Fri, 16 Oct 2026 09:23:08 +0000

Open the Performance tab, record five seconds of a dashboard with a live "3 new messages" counter in the corner, and look at the flame chart. There's a good chance you'll see a Layout block fire every time that counter ticks — not sized to one <span>, but spanning a chunk of the page that has nothing to do with it.

Nobody wrote code that does that on purpose. The browser just doesn't know any better: by default, a change anywhere in the DOM is a reason to ask whether anything outside that element needs to be measured again. A <span> updating its text could, in principle, change its own size, which could push its parent, which could push a sibling, which could ripple all the way out. The layout engine can't assume otherwise, so for anything it isn't sure about, it checks.

That's the part almost nobody profiles for, because the obvious suspect is always JavaScript.

The fix everyone reaches for first: throttle the JS

Say the counter updates from a WebSocket message every couple of seconds, and someone notices the jank. The first instinct is almost always to blame the handler:

socket.onmessage = (e) => {
  // "it's probably firing too often" — throttle it
  updateCounterThrottled(e.data);
};

Sometimes that genuinely helps, if the handler is doing real work. But plenty of the time the handler is one textContent assignment, the throttle buys nothing, and the Layout block in the profiler is exactly the same width as before — because throttling how often something changes doesn't change how much the browser has to re-check each time it does. The cost was never in the JS. It was in what layout had to consider every time that one element changed.

What's actually happening: layout has no boundaries by default

Every element in the DOM is, by default, part of one connected layout problem. There's no built-in notion of "this subtree is self-contained" — the browser has to be conservative, because CSS gives it plenty of ways for a tiny element to affect something far away: a child wider than its parent, a negative margin, an absolutely positioned descendant escaping its ancestor, intrinsic sizing that depends on content. Any of those could be happening, so near any DOM change, the engine re-checks more than the one element that changed.

This is the part the Myth "if it's slow, profile the JS" misses: sometimes the JS is one line, and the real cost is a layout engine doing its job correctly with no boundary to stop at.

The fix: draw the boundary yourself

CSS containment exists to let you make that promise explicit. contain: layout tells the browser: whatever happens inside this element, it does not affect anything outside it — and nothing outside affects its internal layout either. That's not a performance hint the browser might ignore, the way will-change is; it's a contract. Once you've made it, the engine can stop checking past the boundary.

.widget {
  contain: content; /* layout + style + paint, no size */
}

contain takes several keywords, and they compose:

layout — the element's internal layout can't leak out, and outside layout can't reach in. This is the one that stops the ripple.
paint — nothing the element paints (or its descendants paint) can render outside its own box. The browser can skip painting it entirely if it's off-screen or hidden.
size — the element's size can be computed without looking at its contents at all. Powerful, but it has a real catch (below).
content is shorthand for layout paint style together. strict adds size on top of that.

Add layout paint (or content) to that counter widget's wrapper, and the Layout block in the next profile is scoped to the widget — the rest of the dashboard stops showing up in it, because the browser now has a guarantee it didn't have before.

🎮 Try it yourself

▶️ Open the interactive playground →

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

The gotcha: `size` containment can collapse your element to nothing

Here's where people get burned. contain: strict sounds like the "turn it all on" option, and size containment is the part that quietly breaks things:

/* looks safe — it's not, if .widget has no explicit height */
.widget {
  contain: strict;
}

Size containment means the browser computes this element's size as if it had no content — on purpose, that's the whole point, so it never has to wait on the subtree to know how much space to reserve. But "as if it had no content" means an element with no explicit width/height (or aspect-ratio) and no content to size from collapses toward zero. The widget doesn't jank anymore. It just silently stops taking up space, and you find out from a bug report, not a profiler.

The fix is to pair size containment with an explicit size:

.widget {
  contain: strict;
  width: 280px;
  height: 120px; /* or min-height, or aspect-ratio */
}

This is exactly the trade content-visibility: auto makes for you automatically when an element scrolls off-screen — it's contain: layout style paint, plus size containment kicked in conditionally, which is why that property asks you to set a contain-intrinsic-size placeholder. contain on its own gives you the same lever with none of the training wheels: you decide which boxes get which guarantees, and you're responsible for the size one.

One more side effect worth knowing before you add this everywhere: layout, paint, content, and strict all turn the element into a new containing block for absolutely- and fixed-positioned descendants, and a new stacking context. A child using position: fixed to escape to the viewport, or a dropdown relying on position: absolute against some ancestor further up the tree, will suddenly anchor to your newly-contained box instead. That's rarely what breaks a dashboard widget — but it's exactly what breaks a modal or a tooltip if you reach for contain on a wrapper without checking what's positioned relative to it.

When plain, uncontained CSS is still the right call

Most elements on most pages don't need this. A static hero section, a footer, a paragraph of text — none of it changes after paint, so there's nothing for containment to isolate it from. Containment earns its keep specifically where something changes on its own schedule independent of the rest of the page: live counters, chat widgets, auto-refreshing tickers, anything driven by a timer or a socket rather than user navigation. If you haven't opened the Performance tab and actually seen a Layout block wider than the element that triggered it, you don't have evidence containment will help — you have a hunch, and contain: strict on a hunch is how an element quietly collapses to zero height.

The takeaway

The layout engine isn't being wasteful when it re-checks more than you expected — it's being correct, given that it has no way to know your widget is self-contained. contain is how you tell it. Scope it to the one element that changes on its own, pick layout paint (or content) first, and only reach for size / strict once that element has an explicit size to fall back on. The profiler cost that looked like a JavaScript problem was a missing boundary the whole time.

Go record a profile on the one thing on your page that updates without a page reload — a counter, a ticker, a live status dot — and check whether the Layout block is scoped to it. What did you find?

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

Stop Electing a Leader Tab. SharedWorker Just Holds the Connection.

Parsa Jiravand — Thu, 15 Oct 2026 06:10:31 +0000

Last week's fix for "six tabs, six WebSockets" was navigator.locks: elect one tab as leader, let it hold the one real connection, relay everything to the rest over BroadcastChannel. It works. I said as much at the time.

It also has a seam I didn't dwell on: the connection lives inside a tab. Close that tab — the user's doing, not a bug — and the lock releases, a new leader gets picked within the same event loop turn, and that new leader still has to open a brand-new WebSocket from scratch. Real handshake, real round trip, real gap before updates resume. For a dashboard, nobody notices. For a live price ticker or a shared cursor, that gap is the whole ballgame.

There's a version of this where no tab ever owns the connection, so no tab closing can take it away.

The belief: something has to own the socket

The leader-election pattern isn't wrong. It's the correct answer to a real constraint: a WebSocket object lives in some JavaScript execution context, and until recently the only context every tab could reliably reach was another tab's. So you pick one, crown it leader, and accept that leadership — like any job held by one person — has a handoff cost when that person leaves.

// what every tab currently runs
navigator.locks.request("app-connection-leader", () => {
  const socket = new WebSocket("wss://example.com/live");
  socket.onmessage = (e) => channel.postMessage(e.data);
  return new Promise(() => {}); // held until this tab closes
});

This is fine code. It's also solving "how do we share one connection" by picking which page gets to be the exception — which means the exception goes away the moment that page does.

The context that outlives every tab

A SharedWorker is a separate execution context, like a regular Worker, except more than one tab can connect to the same instance of it at once. The browser starts it the first time any tab asks for it by URL, keeps it running as long as at least one tab is still connected, and every tab talks to it through its own MessagePort — a direct, two-way pipe into one shared scope that was never inside any of their tabs to begin with.

// live-feed-worker.js
let socket;
const ports = new Set();

self.onconnect = (event) => {
  const port = event.ports[0];
  ports.add(port);

  if (!socket) {
    socket = new WebSocket("wss://example.com/live");
    socket.onmessage = (e) => {
      for (const p of ports) p.postMessage(e.data);
    };
  }

  port.onmessage = (e) => socket.send(e.data); // tab -> server, through the one socket
};

// every tab, on load
const worker = new SharedWorker("/live-feed-worker.js");
worker.port.onmessage = (e) => renderUpdate(e.data);

That's the whole wiring. No election, because there's nothing to elect a leader for — the worker opens the socket once, the first time ports.size goes from zero to one, and every tab after that just gets handed a port into a worker that's already running. Close the tab that happened to open first, second, or fifth: socket doesn't move, because it was never that tab's to carry.

One detail worth getting right: setting port.onmessage directly starts the port automatically. You only need an explicit port.start() call if you wire the port with addEventListener("message", …) instead — the implicit start only fires off the property setter.

🎮 Try it yourself

▶️ Open the interactive playground →

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

The puzzle this trades in

Removing the leader doesn't remove every problem — it swaps one for a quieter one. navigator.locks tells you, immediately and for free, the moment a tab is gone: the lock releases the instant the tab closes, crashes, or navigates away, because the browser is the one holding the lock and the browser knows. A SharedWorker gets no such notice. There is no standard "this port just disconnected" event — a port left behind by a closed tab just sits in your Set, reachable only by postMessage calls that go nowhere, until the browser eventually garbage-collects it on its own schedule.

That's invisible at first — a few dead ports costs you nothing but a wasted loop iteration — but it means you can't use "how many ports do I have" as a live headcount, and you can't reliably ask "is anyone still connected" to decide when to close the real socket. The fix is the same one people have used since shared workers existed: don't wait to be told, say so on the way out.

// every tab
addEventListener("pagehide", () => {
  worker.port.postMessage({ type: "closing" });
});

// live-feed-worker.js
port.onmessage = (e) => {
  if (e.data?.type === "closing") {
    ports.delete(port);
    if (ports.size === 0) socket.close();
    return;
  }
  socket.send(e.data);
};

Two extra lines on each side, and now the worker's idea of "who's connected" matches reality closely enough to act on — close the real socket once the last tab says goodbye, instead of leaving it open for a page that's already gone.

Browser support, honestly

Desktop Chrome, Firefox, and Edge have supported SharedWorker for a very long time, and Safari added it in version 16 — including iOS Safari 16, which is the gap that used to rule this API out for anything mobile-facing. The one real asterisk: Chrome for Android didn't support SharedWorker at all for years, specifically because of unpredictable process-lifecycle behavior on mobile, and only gained support in a 2026 release. If a meaningful slice of your traffic is Android Chrome on an older version, check caniuse.com's current numbers against your own analytics before you rely on this being universal — and keep last week's navigator.locks pattern in your back pocket as the fallback that works everywhere today, Android included.

No leader, no handoff, one quieter problem instead

The leader-election pattern isn't obsolete — it's still the one answer that works on every browser shipping today, and it's still the right call if your Android numbers say you can't assume SharedWorker yet. But where it's available, it removes the actual thing that made leader election necessary: a connection that has to live inside some tab's lifetime. A SharedWorker's connection lives in its own context, outside every tab equally, so closing any one of them — including the tab that happened to open it first — costs nothing at all.

Go check whether your app's "shared" state actually lives independently of every tab, or just inside whichever one got there first. What's the oldest "pick a tab to be special" hack you're still running?

🧠 Test yourself

Think it clicked? Take the 7-question quiz →

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

📚 Read next

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

Thanks for reading! Let's stay connected:

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

I Turned 44 Blog Posts Into a Frontend Roadmap You Have to Pass

Parsa Jiravand — Wed, 14 Oct 2026 19:50:47 +0000

It's Sunday night, the interview is on Thursday, and the frontend roadmap in your other tab has more topics than you have evenings. You're sure about half of them and fairly sure about the rest.

The roadmap can't tell you which "fairly sure" is real. It only knows what you ticked.

So test the topics before you read them. Here's what that looks like for HTML: ten questions drawn at random, seven right to pass, and the whole stage counts as cleared.

No account and no reading, just ten questions. Here's why that beats a checkbox, and how it works.

What you'll learn

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

Explain why a frontend roadmap you tick yourself overstates what you know, using a 2006 study of re-reading versus testing
Compare seven well-known frontend roadmaps and courses on price, sign-up, checks, skipping and certificates
Use checkpoints to skip the stages you already know and find the gaps you don't
Compute learning progress from quiz attempts instead of storing it
Tell when this path is the wrong tool, and what to use instead

Who this is for

You've shipped frontend code for a year or more, in Vue or React, and you want to find out quickly what you actually know: for an interview, a promotion or your own peace of mind. If you build learning tools, read "Under the hood". If you're starting from zero, read "When not to use it" first.

Why a frontend roadmap you tick yourself stops working
What people do today: seven frontend roadmaps and courses
Where today's options break
The mental model
Enter the Frontend Developer path
How the frontend roadmap works, in four steps
Under the hood: progress computed from quiz attempts
When not to use it
FAQ
Cheat sheet: the path at a glance

Why a frontend roadmap you tick yourself stops working

Strip a self-marked roadmap down to its data, and this is all of it:

type Status = "done" | "learning" | "skipped" | "pending";

const progress: Record<string, Status> = {
  "semantic-html": "done",  // ticked two years ago
  "event-loop": "done",     // read the article, felt fine
  promises: "skipped",      // "I use them every day"
  specificity: "pending",
};

Every value in that object is an opinion, typed in by the person it describes. Nothing can make it wrong, and that is the bug.

It fails in three ways:

"done" records reading, not knowing. Reaching the end of an article and answering a question about it are different events. The tick records the first one.
"skipped" is a guess, in both directions. You skip HTML because you've written it for years. Whether you know what inert does, or what showModal() gives you that show() doesn't, the tick can't say. Some of what you skip, you don't know; some of what you re-read, you did.
Nobody else can read it. A lead, a mentor or an interviewer can't tell your "done" from anyone else's.

The fix isn't a better checkbox. It's taking the checkbox away from the person being measured.

What people do today: seven frontend roadmaps and courses

Here's how the best-known options handle it, checked on their own pages on 14 October 2026:

	Free?	Account	How your learning is checked	Skip what you know	Certificate
roadmap.sh frontend roadmap	Yes; AI quizzes: 2 on the free plan, unlimited on Pro ($10/month)	To save progress	You mark topics done; AI quizzes and self-graded flashcards sit alongside	Mark a topic "skipped" yourself	None found
freeCodeCamp v9 certifications	Yes	To save progress	Questions after every lesson, 20-question module quizzes, 5 projects, then a 50-question closed-book exam	No placement test found	Yes, free
The Odin Project	Yes	Optional, to check off lessons	Projects, compared with other students' solutions	Cherry-pick lessons and projects	"We don't provide a certificate"
MDN Curriculum	Yes	No	Not graded: a syllabus with recommended resources, plus "Test your skills" self-checks in MDN's Learn modules	A self-paced reading list	None
Codecademy Front-End Engineer	No: Pro, from $15.99/month billed annually	Yes	103 quizzes, 77 projects, certification exams	"Skip ahead to the exam"	Professional certification (Pro)
Scrimba Frontend Developer path	No: subscription	Yes	Coding challenges inside the screencasts, solo projects, some quizzes	None found	Certificate of completion
Frontend Mentor learning paths	Mostly	To submit (GitHub login)	Feedback on what you build: the community, plus AI review (1 a month free, every solution on Pro)	Pick any challenge	None found

Three of these deserve more than a row.

roadmap.sh is the best map of what to learn. Its roadmaps are free, the project has 369K GitHub stars, and the site counts more than 3.2 million registered users. If you want to know what exists, look there first; nothing here argues against it.

freeCodeCamp's v9 certifications are the most rigorous free credential in that table, and more rigorous than the quizzes in this article. The new Responsive Web Design certification ends each lesson with three comprehension questions and each module with a 20-question quiz (18 right to pass). Then it asks for five certification projects before a 50-question, closed-book exam: one attempt a week, reviewed by staff before the result is released.

The Odin Project is right about proof. It gives no certificate because, in its FAQ's words, "Employers will be much more impressed with your amazing personal portfolio of projects." Projects are the strongest evidence anywhere in that table.

Where today's options break

None of these is broken. The gap only shows when you want four things at once: free, no sign-up to start, a check on every step, and a skip you have to earn.

On roadmap.sh you mark a topic done. Its AI-generated quizzes sit beside the roadmap rather than gating it: two on the free plan ("These don't reset"), unlimited on Pro at $10 a month. freeCodeCamp checks properly, but it is built to take you from the start: its own figure is 300 hours per certification, and the exam waits for five projects. Right for learning, heavy for finding out what you already know.

Codecademy built exactly the skip I wanted ("Don't waste time learning what you already know") and put it behind Pro, from $15.99 a month billed annually. The Odin Project and MDN Curriculum have nothing to pass, Scrimba is paid, and Frontend Mentor checks what you build rather than what you know.

No single piece of what I built is new; quizzes, skipping, forks and certificates all exist in that table. What I couldn't find among those seven was all four together.

The mental model

The mental model: reading is input, answering is evidence, and progress should be computed from the evidence, never typed in by the person being measured.

The evidence isn't only for other people. Roediger and Karpicke's 2006 study, Test-Enhanced Learning (Psychological Science 17(3), 249–255), compared re-reading with testing. On a test five minutes later, re-reading came out ahead. Two days later, and again a week later, testing did, even though re-reading had left students more confident. No feedback was given in that study: nobody told the tested students what they had missed.

Three things follow:

Skipping is evidence arriving early. If you can pass the check without reading, the reading would have been re-reading, the strategy that lost at two days and at a week.
A check can be open-book and still be a check. Its job is to make you answer, and to show you exactly where you couldn't.
Failing is the useful part. A wrong answer that arrives with an explanation is a reading list. A tick never told you anything.

Enter the Frontend Developer path

I'd already written the articles. Between July and October, 44 of my posts each taught one piece of frontend, from the native <dialog> to the back/forward cache, and every one has a quiz. What they lacked was an order, and a reason to take the quiz.

So I put them on a map: a free frontend developer roadmap on bestpractic.org, where every step is an article and a quiz you have to pass. Read it. Pass it. Unlock the next stage.

Honestly, in one sentence: 44 existing articles and their 336 quiz questions, in 7 stages that each close with a checkpoint, free, with no account needed to start, about 16 hours by the site's own estimate, and 7 more levels still being written.

🗺️ The map: https://bestpractic.org/paths/frontend-developer
⏭️ The HTML checkpoint: https://bestpractic.org/paths/frontend-developer/checkpoint/html
1️⃣ Level 1, the native <dialog>: https://bestpractic.org/blog/dialog-element-native-modal?path=frontend-developer
📚 All learning paths: https://bestpractic.org/paths

How the frontend roadmap works, in four steps

Step 1: the map

The route has seven stages: HTML, CSS, JavaScript, Vue or React, Nuxt or Next.js, TypeScript, and Ship it, the production stage. The two forks make nine stage cards, each pair sharing one tier of the map: Nuxt follows Vue, Next.js follows React, and TypeScript opens from either side.

The longest route is 34 levels, through Vue and Nuxt; through React and Next.js it is 33. JavaScript includes the event loop, Next.js starts with Cache Components, and TypeScript with generics. Seven more levels show as "Being written": from-zero openers for HTML, JavaScript, Vue and React, then the box model and cascade, Flexbox, and inferred type predicates.

Key concept: the percentage measures your route, not the whole map. Each tier counts once, so finishing one branch is 100%.

Step 2: a level is an article plus its quiz

Each level is one of the 44 articles plus its quiz: 6 to 9 questions, four options each. The article's badge says where it sits ("Level 1 of 4 in HTML"). Pass the quiz at 70% to clear the level. Your best score counts, retakes are unlimited, and each cleared level leaves a crystal on the map, gold at 100%.

Answers stay hidden until you submit. Then every question is explained: why the right option is right and, if you picked another, why yours was wrong. Two-thirds also link to a source, mostly MDN and the frameworks' own docs.

Levels open one at a time. A locked one is still readable: its drawer offers "Read it anyway", because every article is free.

Key concept: the lock orders the route; it never hides the article. A quiz you passed before its level opened, from the blog, say, still counts.

Step 3: the checkpoint, and how to skip a stage

Every stage ends in a checkpoint: 10 questions drawn at random from that stage's level quizzes, a fresh draw on each attempt, 70% to pass. The last one, Ship it, draws 15. Beat it, and the stage is clear and the next one opens.

A checkpoint is open from the moment its stage is. That's the skip from the top of this article: "Know HTML? Skip it" goes straight there, and a pass clears HTML without a single level. The levels stay open, so you can go back for the crystals; skipping earns none.

Fail it, and the review explains every question; the next attempt is a new draw. One honest caveat: a checkpoint has no questions of its own, so if you have just cleared every level in a stage, you have already met every question it can ask.

Key concept: a checkpoint is a placement check built from the stage's own quizzes. It asks the same of someone who read everything and someone who read nothing.

Step 4: your run, and the finish line

No account is needed to start: a guest's run is saved on that device for a year, in a cookie set when you first start a quiz. Sign up, and your guest attempts move to your account, run and all.

The "Your run" card does the arithmetic. Clear level 1 and you're at 3%: one of five units in HTML (four levels plus the checkpoint), averaged over seven tiers. Beat the HTML checkpoint and you're at 14%.

You finish by beating one checkpoint per tier: seven passes, at least 75 questions. The certificate needs a free account and lives at a public link (/certificates/BP-…) that anyone can open to check it. It states what it certifies: earned by every checkpoint.

Key concept: finishing is defined by checkpoints alone, which is why a skipper and a completionist end up at the same finish line.

Under the hood: progress computed from quiz attempts

If you build learning tools, this is the part worth taking.

Progress is computed, not kept. The map never reads your progress from a table; every load works it out again from the map and your best attempt at each quiz. The real path-progress.ts is covered by 13 Vitest cases. This simplified sketch follows the same rules:

// A simplified sketch of path-progress.ts. The real one also places the "You"
// marker, follows the branch you started at a fork, and marks perfect scores.
type Stage = {
  slug: string;
  tier: number;              // forks share a tier: Vue and React are both 4
  unlockedBy: string[];      // [] for HTML, ["nuxt", "nextjs"] for TypeScript
  checkpoint: string;        // the checkpoint's quiz id
  levels: (string | null)[]; // level quiz ids in order; null = "Being written"
};
type Attempt = { quiz: string; score: number; maxScore: number };

export function pathProgress(stages: Stage[], attempts: Attempt[]) {
  // 1. Only your best attempt at each quiz counts, wherever you took it.
  const best = new Map<string, number>();
  for (const { quiz, score, maxScore } of attempts) {
    best.set(quiz, Math.max(best.get(quiz) ?? 0, (score / maxScore) * 100));
  }
  const passed = (quiz: string) => (best.get(quiz) ?? 0) >= 70;

  const ordered = [...stages].sort((a, b) => a.tier - b.tier);
  const cleared = new Set<string>();
  const levels = new Map<string, "open" | "locked" | "cleared">();

  for (const stage of ordered) {
    // 2. A stage opens when ANY stage in its unlockedBy is cleared.
    const open = stage.unlockedBy.length === 0 || stage.unlockedBy.some((s) => cleared.has(s));
    // 3. Its checkpoint, and nothing else, clears it.
    if (open && passed(stage.checkpoint)) cleared.add(stage.slug);

    // 4. Levels open one at a time. A "Being written" level is skipped: it blocks nobody.
    let previousPassed = true;
    for (const quiz of stage.levels) {
      if (quiz === null) continue;
      const ok = passed(quiz);
      levels.set(quiz, ok ? "cleared" : open && (previousPassed || cleared.has(stage.slug)) ? "open" : "locked");
      previousPassed = ok;
    }
  }

  // 5. Percent along your route: each tier counts once, scored by its best
  //    stage, and a checkpoint is worth one level.
  const tiers = [...new Set(ordered.map((s) => s.tier))];
  const tierScore = (tier: number) =>
    Math.max(...ordered.filter((s) => s.tier === tier).map((s) => {
      if (cleared.has(s.slug)) return 1;
      const written = s.levels.filter((q): q is string => q !== null);
      return written.filter(passed).length / (written.length + 1);
    }));
  const pct = Math.round((tiers.reduce((sum, t) => sum + tierScore(t), 0) / tiers.length) * 100);

  return { cleared, levels, pct };
}

That one decision pays for four features:

Guests get a working map with no account, because their quiz attempts were already rows, keyed to a cookie.
A quiz passed on the blog before the path existed counts the day the path does.
Adding a level needs no backfill.
Signing up keeps the run, because the run was only ever the attempts.

A signed-in run also writes its latest percentage to an enrollment record, after the fact; the map never reads it back. The rest follows the same instinct:

The map is the same for everyone; you are fetched. The server renders the map without anyone's progress in it, so every visitor gets the same one. Your place on it arrives after hydration, and the default is a newcomer's view, so a first visit never shows padlocks flicking open.
Looking costs nothing. The progress endpoint never sets a cookie. The anonymous ID is only set when there is something to save, like a quiz attempt, so a crawler that only looks never gets one.
Forks are data. Each stage lists the stages that open it (unlockedBy), and the map draws one road per entry: the line, the fork and the join, from one rule.
Checkpoints are assembled, not written. Each release builds a stage's checkpoint from its level quizzes. They issue no certificate of their own; the path certificate is the proof.
The catalogue is code. A level whose article isn't written yet shows as "Being written" and blocks nobody. Publishing that article and its quiz under the planned slug is all the map needs; the next release picks it up.

When not to use it

Here's when this path is the wrong tool, and what to use instead.

You're starting from zero today. The from-zero openers aren't written yet, and the first live level, the native <dialog>, assumes you've built a modal before. Start with the MDN Curriculum, free and beginner-level, or freeCodeCamp for questions after every lesson, and come back for the checkpoints.
You learn by building. A quiz checks understanding, not whether you can ship a page. The Odin Project is free and project-based, and Frontend Mentor gives you real designs to build, with feedback on the result.
You need a closed-book credential. These quizzes are open-book and unsupervised. freeCodeCamp's v9 certifications end in a closed-book exam and cost nothing.
You learn from video. Every level here is text. Scrimba's Frontend Developer path is about 81 hours of interactive screencasts, on a paid plan.
You want the whole map of the field. This is one path through 44 articles; roadmap.sh shows everything around it.
You work in Angular or Svelte. The forks are Vue and React only.
You'll switch devices before signing up. A guest run lives in one browser, and clearing its cookies loses it. Create the free account first.

FAQ

Is this frontend roadmap really free?

Yes. Every article, quiz and checkpoint on the path is free, and so is the account the certificate needs.

Do I need an account to start the frontend roadmap?

No. A guest run is saved on that device for a year. A free account carries it to every device, keeps what you did as a guest, and is required for the certificate.

How long does the frontend developer roadmap take?

The site estimates about 16 hours for one route; the read-time labels alone add up to 324 minutes on the Vue route and 302 on the React one. Skip everything you can, and the floor is seven checkpoints: 75 questions.

Should I learn Vue or React first?

The path doesn't rank them. Both open when you clear JavaScript, and TypeScript opens after either Nuxt or Next.js, so neither branch is a dead end. Pick the one your job, or the job you want, uses; your percentage only counts one branch.

Can I skip HTML and CSS?

Yes, if you can pass their checkpoints, 7 of 10 on each. Beat HTML's and CSS opens; beat CSS's and JavaScript opens. A stage only counts once it is open, so you skip in order.

What happens if I fail a checkpoint?

Nothing is lost. The review explains every question you missed, and you can retake it straight away: each attempt is a new random draw, with no cooldown and no attempt limit, and your best result counts.

Is the frontend developer certificate worth anything?

It records one thing: that the named account passed one checkpoint per stage at 70% or better, open-book, at least 75 questions in all. Anyone can open its public link to check it. It is not a closed-book credential; freeCodeCamp's is the free one built for that. Treat it as a receipt, not a diploma.

Cheat sheet: the path at a glance

The numbers below come from the live map as of 14 October 2026; "live levels" counts written levels only.

Stage	Live levels	Checkpoint	Two example levels
1 · HTML	4	10 questions, 7 to pass	Native `<dialog>`, The inert attribute
2 · CSS	5	10 questions, 7 to pass	Specificity with `:where()`, Viewport units: dvh, svh, lvh
3 · JavaScript	6	10 questions, 7 to pass	Closures, The event loop
4 · Vue (or React)	6	10 questions, 7 to pass	ref vs reactive, Composables & shared state
4 · React (or Vue)	5	10 questions, 7 to pass	Re-render vs remount, React Compiler
5 · Nuxt (after Vue)	5	10 questions, 7 to pass	useAsyncData keys, Hydration mismatches
5 · Next.js (after React)	5	10 questions, 7 to pass	Cache Components, proxy.ts
6 · TypeScript	3	10 questions, 7 to pass	Generics, `satisfies`
7 · Ship it	5	15 questions, 11 to pass	Core Web Vitals, Web Workers

That's 44 written levels across both forks, 34 on the Vue route and 33 on the React route, plus 7 being written.

The rules in five lines:

level       article + quiz (6–9 questions). Pass at 70%; your best attempt counts.
order       Levels open one at a time. A locked article is still free to read.
checkpoint  10 random questions from the stage (15 for Ship it). 70% clears it.
skip        A checkpoint is open as soon as its stage is. Beat it early to skip.
finish      One checkpoint per tier. Certificate: free account, public link.

Key takeaways

A tick you give yourself records what you read, not what you can answer. Compute progress from answers.
In Roediger and Karpicke's 2006 study, re-reading won at five minutes; testing won at two days and at a week, with no feedback.
Skipping is evidence arriving early: pass the check, and the reading was optional.
Building a learning tool? Store the attempts and derive everything else.

Back to Sunday night, and the roadmap that only knows what you ticked. Spend the first evening on checkpoints instead of chapters. The stages you pass are done, and the ones you fail hand you every missed question, explained: a better reading list than a column of ticks ever was.

Which checkpoint do you think you could pass without reading anything, and which one would surprise you?

Written with AI assistance; every fact checked against the live site and primary sources.

🚀 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
📸 Instagram — frontend best practices, daily: @bestpractice___

Remote work means someone else is telling your story for you

Parsa Jiravand — Wed, 14 Oct 2026 06:10:59 +0000

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

It's a Tuesday afternoon somewhere you've never been, in a room with a whiteboard you've never stood in front of, and three or four people are deciding whether you get the promotion this cycle. One of them is your manager. The rest are working entirely off what your manager says, because none of them have ever actually watched you do the job.

That room exists whether you're remote or not. The difference is what reaches it.

What's actually happening

In an office, you get credit by osmosis. Someone walks past while you're debugging the thing nobody else wanted to touch. Someone overhears you explain a tradeoff clearly in a hallway and mentions it later without even meaning to vouch for you — it just stuck. None of that is a system. It's ambient noise, and some fraction of it drifts into the room where decisions get made, without your manager having to do anything on purpose.

Remote, that channel is just gone. There's no ambient noise to drift anywhere. So the entire account of your work that makes it into that room is the one your manager constructs — consciously, from memory, usually under time pressure, usually compressed into a sentence because that's all the agenda allows for each person. And building an accurate, compelling account of somebody else's quarter, from memory, in thirty seconds, is a specific skill. It is not the same skill as being good at your job, and it's not the same skill as being a good manager generally, either. Some excellent managers are quietly bad at this one narrow thing, and you'd never know it, because the only symptom is that you don't get mentioned.

So the real situation isn't "remote work hurts your visibility." It's narrower and more useful than that: when you're not in the room, you are depending on someone else's memory and someone else's narration, and that dependency is usually invisible to you until a cycle goes by where it clearly didn't work.

It also compounds in a way that's easy to miss. One quiet cycle doesn't feel like much — you tell yourself it was a slow quarter, or the timing was off. But the mechanism doesn't reset between cycles. If your manager's account of you was thin in March, it's still the most recent account in their head come September, because nothing replaced it in between. You don't notice the pattern until you look back at two or three cycles in a row and realize the same thing happened each time, for the same reason, and you'd been treating each one as a one-off.

This is part of why some companies have started pulling people back into buildings — not because the work can't be done remotely, but because this exact gap is expensive for them too, and a desk is a cheaper fix for them than training managers to narrate well. That's a real tradeoff happening at a lot of places right now, and it's worth naming plainly: the office was never solving this problem on purpose, it was solving it as a side effect, and now that some companies don't have that side effect anymore, a few of them are buying it back the blunt way instead of the deliberate way. You don't have to agree with that choice to understand why it's being made.

So what do you actually do about it

You can't be in the room. But you can stop leaving the narration entirely to memory.

The clearest move: before the thing happens — the review, the calibration meeting, the 1:1 where the cycle gets summarized — tell your manager the sentence you'd want them to use. Not a list, one sentence: "Before you go in, can I tell you the one thing from this project I'd most want remembered? Might save you digging for it." That's it. You're not asking for credit. You're handing someone who already has to improvise a summary the exact line that improvisation would otherwise cost them time to find.

The second move is timing. Do this before the gap shows up, not after. If you wait until you notice you weren't mentioned, the conversation becomes about repairing an omission, which is a worse conversation for both of you. Send the sentence a week ahead, as part of a normal update, not as a special request: "heads up, the thing I'd flag from this sprint is the retry logic — it's the reason the on-call load dropped, and I'm the only one who has the context on how it's wired." You're pre-loading the material. Nobody has to remember anything, because it's already written down in their own inbox.

The third is for when it still doesn't land — you find out after the fact that you weren't mentioned, or mentioned thinly. The instinct is "that's not fair," which is true and also gets you nothing, because it reads as a complaint about an outcome nobody can undo. Ask instead: "Can you tell me how that came across in calibration? I want to understand so I can be clearer next time." Same frustration, completely different conversation. One asks someone to defend a decision. The other asks them to hand you information. People will give you the second thing far more easily than they'll give you the first.

Where this goes wrong

Send that sentence every two weeks and it stops being a heads-up and starts being a campaign. Managers notice when every update doubles as a resume bullet, and the material that would've worked once starts reading as managing them instead of informing them. Once a quarter, around the actual review cycle, is about as often as this holds its shape. More than that, and you've made your manager's job of advocating for you feel like a performance you're staging for them, which is the opposite of what you want.

And there's a version of this that doesn't work at all, no matter how well you word it: if your manager doesn't actually attend the room where this gets decided, or attends it but has no real standing there — overloaded, new, themselves on thin ice — then handing them better material doesn't fix anything, because the room isn't weighing your material, it's weighing whether the person saying it carries any weight. You can't write your way around that one. The problem isn't your sentence. It's that the chain you're depending on has a broken link above the part you control.

There's also a quieter failure mode worth naming: doing this well for someone who then takes the sentence and says nothing with it, every cycle, without ever telling you why. At some point that stops being a narration problem and becomes information about whether this is a manager who will ever spend effort on your behalf, regardless of what you hand them. One or two quiet cycles is the normal noise this piece is about. A pattern across a year is a different, harder thing to sit with, and the fix for it probably isn't a better sentence.

The part that isn't fair

Some of this is just luck, and pretending otherwise would be dishonest. You got a manager who's a careful narrator of other people's work, or you didn't. You got a manager with real standing in that room, or you got one who's fighting for their own footing. None of that is something you can fix by being better at sending the right sentence at the right time. The sentence helps the part that's reachable. It does nothing for the part that isn't, and the honest thing is to say that plainly instead of implying that enough self-advocacy closes every gap, because it doesn't.

It's also worth saying that the office genuinely does give people something remote doesn't — that ambient, unearned visibility is real, and it's not nothing. The answer isn't to insist remote and in-office are secretly equal, because for this one specific thing, they aren't. The answer is to do on purpose what the office does by accident: get the sentence into the room through the one channel you actually have, which is the person standing in it.

Monday

Before your next 1:1, send your manager one sentence: the single thing from the last few weeks you'd most want remembered, and why. Not a list, not a summary of everything — one sentence, the one you'd want quoted if someone only got to say one thing about you in a room you'll never see.

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

Thanks for reading! Let's stay connected:

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

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

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

You Installed a Library for Numbers PerformanceObserver Already Has.

Parsa Jiravand — Wed, 14 Oct 2026 06:10:27 +0000

Your bundle analyzer flags a new dependency after a routine npm install. Two kilobytes, not huge, but you go looking anyway. It's web-vitals — the package half the performance tutorials on the internet tell you to install just so you can console.log three numbers: LCP, CLS, INP.

You open its source expecting something clever. It's mostly PerformanceObserver calls. The exact same API already sitting in your browser, for free, before your bundle even finishes downloading.

So why does nearly everyone reach for the library first? There's exactly one part of this that's genuinely hard to get right by hand — and it's not the part most people worry about.

Measuring LCP by hand takes four lines

Largest Contentful Paint is the easy one. The browser already tracks which element painted the biggest visible chunk of content, and it hands you updates as a better candidate shows up:

new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lastEntry = entries[entries.length - 1];
  console.log("LCP so far:", lastEntry.startTime, lastEntry.element);
}).observe({ type: "largest-contentful-paint", buffered: true });

buffered: true is the part people forget and then can't figure out why their observer logs nothing — it backfills entries that happened before this script ran, which for LCP is usually all of them, since your analytics script rarely loads before the hero image paints.

The browser keeps revising "largest so far" as bigger elements paint in, and stops for good the moment the user scrolls, clicks, or types, or the tab goes hidden — at that point, whatever the last entry said is the final score. entry.element is the actual DOM node, which is a nice touch for debugging ("oh, the LCP element is the hidden carousel slide, not the headline") — except when it's null, which happens if the element has already been removed from the DOM by the time your callback runs. (A separate gotcha hits cross-origin images without a Timing-Allow-Origin header: element still resolves, but renderTime reads as 0, so you have to fall back to loadTime instead — a different field going quiet, not the element.)

Four lines, one footgun, done. This is not the part web-vitals is earning its keep on.

Where the naive version lies to you: CLS

Cumulative Layout Shift reports as a layout-shift entry every time something visible moves without the user asking it to. Each entry has a .value — how much of the viewport shifted, weighted by distance. The obvious thing to do is sum them:

let clsTotal = 0;
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (!entry.hadRecentInput) clsTotal += entry.value;
  }
  console.log("CLS so far:", clsTotal);
}).observe({ type: "layout-shift", buffered: true });

(hadRecentInput is true if the shift happened within 500ms of the user clicking or typing — an accordion that resizes after you click it shouldn't count against you, so the spec excludes it.)

Ship that on a dashboard that stays open all day, with an ad slot that occasionally reflows, and watch clsTotal climb to 3, then 6, then double digits by the afternoon. Nothing on the page ever visibly jumped badly — a few small shifts, hours apart. The number is technically "correct" by your own code, and it is nowhere close to what the real metric reports, because real CLS was never meant to be a lifetime total.

Before you scroll: what do you think the actual rule is? A cap? A time window? A per-minute budget?

It's a session window. Group shifts where the gap since the last one is under 1 second, cap each group at 5 seconds total, and report whichever single window ever added up to the most:

let windows = [];
let current = null;

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.hadRecentInput) continue;

    const since = entry.startTime - (current?.last ?? -Infinity);
    const span = entry.startTime - (current?.start ?? entry.startTime);

    if (current && since < 1000 && span < 5000) {
      current.sum += entry.value;
      current.last = entry.startTime;
    } else {
      current = { start: entry.startTime, last: entry.startTime, sum: entry.value };
      windows.push(current);
    }
  }
  const cls = Math.max(0, ...windows.map((w) => w.sum));
  console.log("CLS (session-windowed):", cls);
}).observe({ type: "layout-shift", buffered: true });

A burst of shifts from one bad ad reflow — all within a second or two of each other — stays grouped into one window and still hurts your score, correctly. But five unrelated shifts scattered across an afternoon never combine into one number, because they never do to a real visitor either: nobody experiences "all the jank from today," they experience one moment where the page jumped under their thumb.

🎮 Try it yourself

▶️ Open the interactive playground →

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

INP has the same trap, with an extra twist

The naive move for Interaction to Next Paint is to listen for event entries and log every duration:

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    console.log(entry.name, entry.duration);
  }
}).observe({ type: "event", buffered: true, durationThreshold: 16 });

Tap a button on a touchscreen and this fires three or four times — pointerdown, pointerup, click, sometimes more — for what the user experienced as one tap. Log each duration as its own interaction and you've just told your dashboard there were four slow interactions where there was one.

The fix is grouping: every event entry belonging to the same physical interaction shares an interactionId, so you group by that and take the worst duration inside each group — one number per real interaction, not one per DOM event:

const interactions = new Map();

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (!entry.interactionId) continue; // 0 means "not a tracked interaction"
    const existing = interactions.get(entry.interactionId) ?? 0;
    interactions.set(entry.interactionId, Math.max(existing, entry.duration));
  }
}).observe({ type: "event", buffered: true, durationThreshold: 16 });

Even that map isn't the final INP score — the real metric doesn't just report Math.max(...interactions.values()) either. A single freak slow tap (a GC pause at the wrong millisecond) shouldn't define the whole page's score any more than one slow HTTP request should define your p50 latency. The reference implementation tracks a high percentile across the session instead of the single worst value once there have been enough interactions to make a percentile meaningful — which is a few lines of arithmetic you do not want to be debugging for the first time during an incident.

So what is the library actually for?

Not the measuring — you just watched that happen in nine lines. It's the three things nobody gets right the first time they hand-roll this: the CLS session-windowing, the INP interaction-grouping-plus-percentile, and the edge cases around bfcache restores and visibility-change timing that silently double-report or under-report a metric if you don't special-case them. That's real, fiddly logic, and web-vitals has had years of bug reports to get it right. If you're sending these numbers to a real-user-monitoring pipeline that someone makes decisions from, use the library for exactly that math.

Here's the honest caveat, and it's narrower than it would have been a year ago: Safari was the last of the three engines to ship largest-contentful-paint and interaction-level event timing (the interactionId grouping above), adding both in Safari 26.2, December 2025. Firefox isn't new to this — it's had largest-contentful-paint since version 122 (early 2024) — but it only picked up interactionId around the same time as Safari, in Firefox 144. With Safari's December 2025 release, all three engines finally agreed on both entry types, which is what pushed web.dev to mark LCP and INP "Baseline: Newly available" at that point. layout-shift didn't make the trip — Cumulative Layout Shift is still Chromium-only; Firefox's tracking bug for it has sat open since 2021, and Safari 26.2 shipped the other two without it. So CLS is the one metric where neither the raw API nor web-vitals can produce a number for a Firefox or Safari visitor — the library's job there is still correctness on the browsers that do report it, not conjuring data from the one that doesn't. Feature-detect before you rely on any of this:

if (PerformanceObserver.supportedEntryTypes.includes("layout-shift")) {
  // measure it
} else {
  // this visitor is on a browser that can't tell you
}

🧠 Test yourself

Think it clicked? Take the 7-question quiz →

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

The library isn't buying you the measurement — the browser was always going to hand you that, Chromium or nothing. It's buying you the arithmetic that's easy to get wrong exactly once, in production, where you won't notice until the dashboard looks wrong for a month. Have you ever shipped a CLS or INP number you'd now bet was quietly miscounted? I'd genuinely like to know in the comments.

📚 Read next

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

Thanks for reading! Let's stay connected:

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

Your Tabs Each Open Their Own WebSocket. navigator.locks Elects One.

Parsa Jiravand — Tue, 13 Oct 2026 06:11:00 +0000

Open your app in six tabs — most people have at least that many of something open right now — and check your server's connection count. If you're using WebSockets or Server-Sent Events for live updates, it just went up by six. Six sockets, six keep-alives, six copies of every push notification landing in the same browser window.

Nobody asked for six connections. They asked to see their dashboard update live. You gave them that, and also a server bill and a battery drain that scale with how many tabs a bookmark-happy user happens to have open.

The bug you can see in your own network tab

Open devtools, go to the Network tab, filter by WS, and open the same page twice. You'll see two independent socket connections, each sending its own ping, each receiving its own copy of every broadcast the server sends.

Now open six. Your server — which probably caps concurrent connections per deploy, or bills per connection-minute — just got six times the load from one human being. And when the server pushes a notification, that human sees it pop up six times, once per tab, because each tab's JavaScript has no idea the other five exist.

The fix that doesn't fix it

The obvious instinct is the Page Visibility API: pause the connection in background tabs, since the user is only looking at one of them anyway.

document.addEventListener('visibilitychange', () => {
  if (document.hidden) socket.close();
  else socket = new WebSocket(url);
});

This helps a little and breaks something else. A user with the dashboard open on a second monitor, in a visible-but-not-active tab, stops getting updates. Worse, "hidden" and "pointless" aren't the same thing — a background tab doing the actual relaying for a visible one is exactly what you want, not what you're trying to kill.

The real problem was never "which tabs should connect." It's that six tabs are duplicating work that only needs to happen once. You don't want fewer connections scattered unpredictably across whichever tabs happen to be visible — you want exactly one connection, owned by exactly one tab, with the other five just listening in.

That's leader election, and the browser already ships the primitive for it.

navigator.locks, held for the life of a tab

navigator.locks.request() normally looks like a mutex: acquire a named lock, do some work, let it resolve, the lock releases. But nothing requires the callback to resolve quickly. Give it a promise that never resolves on its own, and the lock stays held for as long as that tab is open — the moment the tab closes, crashes, or navigates away, the browser releases the lock for you, automatically, no cleanup code required.

That's the whole mechanism. Whichever tab's request() call wins the (exclusive, FIFO) queue becomes the leader. Every other tab's request just waits — and the instant the leader's tab closes, the next one in line is granted the lock and takes over.

const LEADER_LOCK = 'app-connection-leader';
let socket;

navigator.locks.request(LEADER_LOCK, () => {
  // Only one tab's callback ever runs this at a time.
  socket = new WebSocket('wss://example.com/live');
  socket.onmessage = (e) => {
    channel.postMessage({ tick: e.data }); // fan out to every other tab
    renderUpdate(e.data);                  // and render here too — see why below
  };

  return new Promise(() => {}); // never resolves — holds the lock until this tab dies
});

🎮 Try it yourself

▶️ Open the interactive playground →

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

Relaying to the followers

Electing a leader only solves half the problem — the other five tabs still need the updates. That's what BroadcastChannel is for: the leader relays every message it receives onto a channel that every other tab is already listening to.

const channel = new BroadcastChannel('app-updates');

// Every follower tab runs this:
channel.onmessage = (e) => renderUpdate(e.data.tick);

Here's the gotcha worth knowing before you build this: a BroadcastChannel never delivers a message back to the instance that posted it — that's by design, not a bug. So the leader can't just post to the channel and expect its own onmessage to fire; that's why the leader's socket.onmessage above renders directly instead of waiting for an echo that will never arrive. Followers never touch the real connection — they only ever get updates through the channel. If a follower needs to send something back (a user action, a form submit), it posts that onto the channel too, and the leader is the only one that forwards it to the server. One tab talks to your backend. The rest just listen.

What happens when the leader closes

This is the part worth testing yourself, because it's the part that makes this worth doing at all: close the leader tab, and one of the waiting tabs is granted the lock as soon as the browser notices that tab's context is gone — no polling, no "is anyone still there" timeout, no stale leader lingering for thirty seconds before a new one takes over. The browser's lock queue is the failover mechanism — you don't write one.

There's a brief gap you should know about: the new leader has to open its own WebSocket connection after acquiring the lock, so there's a reconnect delay (normal connection-establishment time) before live updates resume. For a dashboard or notification feed, that's invisible. For something that can't tolerate a gap at all, keep that in mind rather than assuming the handoff is instant.

One more option worth knowing: navigator.locks.request(name, { ifAvailable: true }, callback) checks leadership without joining the queue — callback runs immediately with null if someone else already holds the lock, instead of waiting. Useful for a tab that wants to know "am I the leader?" without volunteering to become one.

Try it with real tabs, not a mental model

Everything above is easy to agree with and easy to get wrong in practice — the FIFO ordering, the automatic release, the reconnect gap. The playground above runs the exact same navigator.locks + BroadcastChannel code in three simulated tabs on one page. Open each one, watch the lock queue hand off leadership the moment you close the leader, and try the "steal" option to see what happens when a tab forces its way to the front instead of waiting in line.

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

Browser support, honestly

navigator.locks is Baseline widely available — Chrome 69+, Firefox 96+, Safari 15.4+ — so this works in every current browser. The one footgun is the steal option: it forcibly yanks the lock away from whoever holds it, skipping the queue entirely. That's occasionally the right tool (a user force-reloading a stuck tab), but use it knowing the previous leader never gets a chance to finish cleanly — it just loses the lock mid-flight.

You don't need six tabs each holding their own connection to do the job of one. You need one tab doing the job, and a browser API that already knows how to pick which one — and hand the job to the next tab the moment the first one leaves.

Does your app open a connection per tab right now? Go count it in the Network panel — I'll bet it's more than you think.

📚 Read next

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

Thanks for reading! Let's stay connected:

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

Next.js 16 Image: priority Deprecated, quality Now Allowlisted

Parsa Jiravand — Tue, 13 Oct 2026 06:10:29 +0000

Your team ships a product page with a hero image: <Image src={photo} quality={90} priority fill />. It looked right in Next.js 15. You upgrade to 16, run a visual regression pass out of habit, and the hero image is... a little softer. Nothing crashed. No error in the terminal. No red line in CI. The quality={90} prop is still sitting right there in the JSX, doing nothing, and you'd have no way to know unless you happened to run the dev server and read a console warning that most people's eyes skip past.

That's the real story behind two changes Next.js 16 made to next/image: the quality prop is now checked against an allowlist (images.qualities, defaulting to [75]), and the priority prop is deprecated in favor of a new preload prop. Neither one is flashy enough to make a release-notes headline, and neither one throws a build error, which is exactly why they're worth a proper look: this article is written against Next.js 16.4 (verified against the framework's own next/image and next.config.js reference docs, and its source in packages/next/src/shared/lib, in October 2026), and by the end you'll know precisely what changed, why, and how to fix it on purpose instead of by accident.

What you'll learn

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

Explain what images.qualities does, why it defaults to [75] in Next.js 16, and what happens to a quality value that isn't on the list
Predict whether a given quality prop gets silently coerced or causes a hard 400, and why those are two different code paths
Migrate priority to preload correctly, and understand why Next.js changed the name rather than the behavior
Read the Version History table at the bottom of a Next.js docs page and use it the way this article does
Configure images.qualities and preload/loading/fetchPriority together without fighting the framework's own validation

Who this is for

You've used next/image in an App Router project — at minimum, you've written <Image src={...} width={...} height={...} /> and set priority on a hero image at some point. You don't need prior knowledge of the Image Optimization API internals; we build the model from the prop down to the request.

The problem: a prop that still compiles but silently does less
The mental model: your props pass through a config-aware layer first
Walkthrough: the quality allowlist
Walkthrough: priority to preload
Edge cases and gotchas
Best practices
FAQ
Cheat sheet
Key takeaways

The problem: a prop that still compiles but silently does less

Here's the Next.js 15 component from the intro, completely ordinary code:

// Works exactly as written on Next.js 15
<Image
  src={photo}
  alt="Studio monitor on a desk"
  fill
  quality={90}
  priority
/>

Upgrade to Next.js 16 with no other changes and two things happen, neither of which raises an error:

quality={90} stops meaning 90. Next.js 16 ships a default images.qualities: [75]. Since 90 isn't on that list, the component silently requests the closest allowed value instead — which, with the default config, is 75. In development you get a console warning. In a production build, there is no warning at all; the image is just a little softer than the designer approved.
priority is marked @deprecated in the type definitions, and the official docs now describe preload as the prop to reach for. Nothing breaks. Nothing tells you at runtime, either — unlike some other deprecated Image props (onLoadingComplete, for instance, logs a warning telling you to switch to onLoad), priority just keeps working, silently, for as long as you keep writing it.

Both changes share the same shape: a prop you set still "works," in the sense that your code compiles and the page renders, while quietly doing something other than what the Next.js 15-era mental model says it does. That's the gap this article closes.

The mental model: your props pass through a config-aware layer first

It's tempting to think of <Image quality={90} priority /> as "pass these two numbers/flags to the <img> tag." It never was that simple, and in Next.js 16 it's explicit: both props go through a validation and normalization layer that consults your next.config.js before anything is requested over the network.

The mental model: <Image>'s props aren't a direct line to the browser. They're inputs to a decision Next.js makes on your behalf, and that decision depends on config you may not have touched. Quality gets snapped to the nearest value your config allows; priority-style loading urgency gets normalized into one signal. In both cases, the component decides what actually leaves your server — your prop is a request, not a guarantee.

Two separate decisions fall out of that model, and they're the two things that changed in 16:

What quality number actually gets requested — governed by images.qualities.
Whether the image loads eagerly and gets a <link rel="preload"> — governed by priority/preload/loading.

Walkthrough: the quality allowlist

Stage 1 — the default, unconfigured app

With no images config at all, Next.js 16's effective default is:

// next.config.js — this is the IMPLICIT default in Next.js 16, you don't have to write it
module.exports = {
  images: {
    qualities: [75],
  },
}

Key concept: every <Image quality={N}> in your app is now checked against this array. If N isn't in it, Next.js doesn't throw — it picks whichever configured value is numerically closest to N and uses that instead.

Stage 2 — what "closest" actually means

This isn't a vague "rounds to a nice number" — it's a specific, small algorithm, and you can reason about it exactly:

// This is Next.js's own logic (shared/lib/find-closest-quality.ts), reproduced for clarity
function findClosestQuality(quality, configuredQualities) {
  const q = quality || 75
  if (!configuredQualities?.length) return q
  return configuredQualities.reduce(
    (prev, cur) => (Math.abs(cur - q) < Math.abs(prev - q) ? cur : prev),
    configuredQualities[0]
  )
}

findClosestQuality(90, [75])           // → 75 (only option)
findClosestQuality(82, [50, 75, 100])  // → 75 (|82-75|=7 beats |82-100|=18)
findClosestQuality(90, [50, 75, 100])  // → 100 (|90-100|=10 beats |90-75|=15)

Try the exact same function with your own numbers in the playground below — it runs this reduction live, not a simplified stand-in.

🎮 Try it yourself

▶️ Open the interactive playground →

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

Stage 3 — configuring it on purpose

If 75 is too aggressive for a photography-heavy site, widen the allowlist explicitly:

// next.config.js
module.exports = {
  images: {
    qualities: [40, 60, 75, 90, 100],
  },
}

Now quality={90} on a component is requested as 90, exactly, because 90 is on the list. The fix for the regression in the intro isn't "add quality back" — it was never removed — it's "put 90 in images.qualities."

Stage 4 — the two different failure modes

This is the part that trips people up, because there are genuinely two code paths, not one:

Through <Image> (the normal path): a disallowed quality is coerced to the closest allowed value. No error, no 4xx — your visitor gets a real image, just at a different quality than you asked for. Development logs a console warning naming the exact value to add to your config; production does not.
Through the raw optimization endpoint (GET /_next/image?url=...&w=...&q=90, the kind of URL you'd get by copying a src out of dev tools, or by hand-building a request): the server validates q against the same allowlist and, if it isn't an exact match, returns a 400 Bad Request. There's no "closest value" leniency here, because this endpoint isn't going through your component's props at all — it's a public HTTP surface, and Next.js treats an unlisted quality value the same way it treats a malformed width: a bad request.

So "what happens if the quality isn't allowed" has two honest answers depending on which door you walked through, and both are intentional: the component degrades gracefully for real visitors; the raw endpoint stays strict so the allowlist can't be bypassed by hitting the optimizer directly.

Walkthrough: priority to preload

Stage 1 — what `priority` always did

priority on <Image> has always done two things together: it stops the image from being treated as lazy-loaded (so the browser doesn't wait to discover it near the viewport), and it has Next.js insert a <link rel="preload"> for it, so the browser's preload scanner can start fetching it before React even renders the <img> tag. That combination is exactly what you want for a Largest Contentful Paint (LCP) candidate — your hero image, the above-the-fold product photo.

Stage 2 — the rename, and why it's a rename and not a behavior change

// Next.js 15 — still compiles on 16, still works, but the type is now @deprecated
<Image src={hero} alt="…" priority fill />

// Next.js 16 — the documented way forward
<Image src={hero} alt="…" preload fill />

Key concept: for the common case — "this is my LCP image, load it with urgency" — preload is a straight swap for priority. Both disable lazy-loading and both trigger the same preload <link> insertion; Next.js didn't change what the prop does here, it changed what it's called, specifically so the name describes the mechanism (a resource preload) instead of a vague notion of importance. You're not supposed to set both: the component throws "Only preload should be used" if a single <Image> has priority and preload together — but, like the quality-coercion warning, that check only runs while NODE_ENV !== 'production', so it surfaces in next dev, not in a next build/next start production run.

Stage 3 — reaching past `preload` when you need more control

The docs are explicit that preload isn't always the right tool, even for an above-the-fold image: "In most cases, you should use loading="eager" or fetchPriority="high" instead of preload." Reach for those two directly when:

// Multiple images could plausibly be the LCP element depending on viewport size —
// don't blanket them all with preload (that fights the browser's own prioritization)
<Image src={hero} alt="…" loading="eager" fetchPriority="high" fill />

preload is a blunt, singular signal — "fetch this one early, with a <link> tag." loading/fetchPriority let the browser's own scheduler make the call across several candidates, which matters once a layout has more than one image that could end up being the LCP element on different screen sizes.

Edge cases and gotchas

Nothing warns you to migrate priority. It's @deprecated in the types (your editor may gray it out or flag it with a linter that reads JSDoc), but there is no runtime console message pointing you to preload, so code that never gets a type-check pass can carry priority indefinitely without anyone noticing it's the old name.
The production quality warning doesn't exist. The images.qualities mismatch warning only fires in development (NODE_ENV !== 'production'). A staging environment running a production build will not tell you a quality prop is being coerced — only next dev will.
A static import's quality is checked too. quality behaves identically whether src is a remote URL, a path under public/, or a statically imported image — the allowlist check doesn't care how the src arrived.
Raising the allowlist raises optimizer work. Every quality value you add to images.qualities is a value the Image Optimization API may actually have to render on demand. A wide allowlist (say, every integer 1–100) defeats the point of having one at all — the docs frame the default narrow list as a deliberate guard against letting "malicious actors... optimize more qualities than you intended," since each distinct quality is a distinct image variant your server (or your hosting provider's optimizer) has to produce and cache.
priority/preload and loading="lazy" are mutually exclusive, and so are priority and preload together. The component throws for either combination rather than silently picking one — but that throw lives in the same NODE_ENV !== 'production'-gated code as the quality warning, so it's a next dev error, not a guarantee your next build/CI pipeline will catch it. If you only ever test with a production build, an invalid combination can ship unnoticed.

Best practices

Set images.qualities once, deliberately, in next.config.js, based on the quality values your designs actually use — don't leave it at the 16 default if your app already standardizes on, say, 85 for photography.
Reserve preload for the one true LCP candidate on a given page. If more than one image could be it depending on viewport, use loading="eager"/fetchPriority="high" on the candidates instead and let the browser's scanner decide.
Run next dev at least once after a major upgrade, specifically to read the console for images.qualities warnings — they don't appear in a production build, and they're the only signal this change produces.
Grep for priority across .tsx files during a 15→16 upgrade and rename to preload as a mechanical pass; it's a safe, behavior-preserving rename for the common usage described above.
Don't widen images.qualities to "everything" as a reflexive fix — pick the two or three values your design system actually ships, the same way you'd pick deviceSizes.

FAQ

Does `quality={90}` throw an error in Next.js 16?

No. If 90 isn't in your images.qualities allowlist, the component silently requests the closest allowed value instead (75, with the default config). No exception, no build failure — just a different number than the one in your JSX. The console warning for this only appears in development.

Why does hitting `/_next/image?...&q=90` directly return a 400 but the component doesn't error?

Because they're different code paths. The <Image> component coerces an out-of-range quality to the closest allowed value before building the request — it never sends an invalid q. The raw optimizer endpoint validates q as a strict allowlist with no coercion, because it's a public HTTP surface that has to reject bad input rather than guess what you meant.

Is `priority` removed in Next.js 16?

No, it's deprecated, not removed. It still compiles and still behaves the same as preload for the eager-load-plus-preload-link use case. The Version History table in the official <Image> reference records it as deprecated starting in v16.0.0.

Do I need to migrate `priority` to `preload` immediately?

Not urgently — there's no runtime warning pushing you to, and the behavior hasn't changed. Treat it like any other mechanical rename: do it the next time you're already touching a file, or as a dedicated sweep during a major-version upgrade, rather than a hotfix.

Does `images.qualities` affect images served through a custom loader?

Only partly. The dev-only console warning for an out-of-allowlist quality fires regardless of which loader you use. But the actual snap-to-closest-value coercion (findClosestQuality) is implemented inside Next.js's own default loader, not in a shared layer every loader passes through — a custom loader function or images.loaderFile receives the raw quality prop exactly as written and is responsible for applying (or ignoring) images.qualities itself. It also isn't going through the /_next/image endpoint in the typical case, so the strict-400 behavior doesn't apply there either.

Cheat sheet

// next.config.js — the Next.js 16 defaults, written out explicitly
module.exports = {
  images: {
    qualities: [75],        // REQUIRED allowlist since v16.0.0; unlisted quality → closest match
  },
}

Task	Code	What actually happens
Request a quality on the allowlist	`<Image quality={75} />`	Requested exactly as given
Request a quality NOT on the allowlist	`<Image quality={90} />` (allowlist `[75]`)	Silently coerced to `75` (closest match); dev-only console warning
Widen what's allowed	`images: { qualities: [50, 75, 100] }`	`quality={90}` now resolves to `100` (closest), not `75`
Hit the optimizer directly with a bad quality	`GET /_next/image?url=...&w=640&q=90` (not on allowlist)	400 Bad Request — no coercion on this path
Mark the LCP / hero image (current)	`<Image preload fill />`	Eager load + `<link rel="preload">` inserted
Mark the LCP / hero image (deprecated, still works)	`<Image priority fill />`	Identical to `preload` — no runtime warning to switch
Multiple possible LCP candidates	`<Image loading="eager" fetchPriority="high" />`	Finer-grained signal than `preload`; lets the browser's scanner weigh several images
Invalid combination (`next dev`-only error)	`<Image priority preload />` or `<Image priority loading="lazy" />`	Throws: "Only `preload` should be used" / "Only one should be used" — only while `NODE_ENV !== 'production'`

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

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

Key takeaways

images.qualities defaults to [75] in Next.js 16. Any quality prop not on your configured allowlist is silently snapped to the closest value that is — gracefully through <Image>, strictly (400) through the raw optimizer endpoint.
The coercion warning is development-only. A production build will not tell you a quality value got rewritten; the only way to catch it is to run next dev and read the console, or to simply set the allowlist to match your design system up front.
priority isn't gone, it's renamed to preload, and for the one thing almost everyone uses it for — flagging the LCP image — the swap is behavior-preserving. Nothing nags you to make it, so plan it as a deliberate pass rather than waiting for a warning that will never come.
loading="eager" + fetchPriority="high" is the more precise tool when a page has more than one plausible LCP candidate; preload is for the single, known one.

You upgrade, the build succeeds, the page looks almost right — and that gap between "compiles" and "renders exactly as specified" is where both of these changes live. Now that you've seen the allowlist and the rename from the inside, a soft hero image or a silently-working priority prop stops being a mystery and starts being a one-line fix in next.config.js or a safe find-and-replace.

If you've been caught by either of these since upgrading to Next.js 16, or found a case the allowlist handles differently than described here, say so in the comments — these are the two next/image changes with the fewest search results and the most "wait, why did my image get softer" GitHub issues.

This episode builds on two earlier ones in this series: Next.js Cache Components Explained covers the broader caching model next/image sits alongside, and Next.js Route Handlers: GET Stopped Caching in 15 is the same "quiet default change with no error message" pattern applied to Route Handlers instead of <Image>.

📚 Read next

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

Thanks for reading! Let's stay connected:

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

Vue watch vs watchEffect: The Complete Guide

Parsa Jiravand — Mon, 12 Oct 2026 06:10:53 +0000

You type "vue" into a search box, one letter at a time. Four requests go out — for v, vu, vue, and the deleted-and-retyped vue again — and the one for v happens to come back last. The screen ends up showing results for a single letter, on top of a watch() callback that looks completely correct. Nothing in that callback is wrong. The watcher just never learned that a newer run had already made it obsolete.

This is the article that fixes that, and along the way answers the question every Vue developer eventually asks: when do I reach for watch(), when do I reach for watchEffect(), and why does my callback keep firing at the wrong moment?

What you'll learn

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

Explain the real difference between watch() and watchEffect() — not "one is explicit, one is automatic," but what that difference costs you
Pick the correct flush timing (pre, post, sync) for a watcher that needs to read the DOM
Use onWatcherCleanup to cancel a stale async response before it overwrites a newer one
Stop a watcher manually, and know when Vue stops it for you
Recognize the specific ways both APIs quietly track (or fail to track) the wrong things

Prerequisites

You should already be comfortable with ref(), reactive(), and computed() in the Composition API. If "why does destructuring a reactive() object lose reactivity" isn't yet second nature, read Vue Reactivity Explained: ref vs reactive first — this article assumes that mental model and builds on it.

This is written against Vue 3.5.x (verified September 2026). Version-specific notes (the once option, onWatcherCleanup) are called out where they apply.

The problem: a watcher with no memory
The mental model: pull vs. push tracking
Stage 1: the smallest watch()
Stage 2: the same job with watchEffect()
Stage 3: multiple sources, and watching inside an object
Stage 4: immediate, deep, and once
Stage 5: flush timing — pre, post, sync
Stage 6: cleanup and the race condition, fixed
Stopping a watcher
Edge cases and gotchas
Best practices
FAQ
Cheat sheet
Key takeaways

The problem: a watcher with no memory

Here's the search box, written the way it's tempting to write it the first time:

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

const query = ref("");
const results = ref([]);

watch(query, async (q) => {
  if (!q) {
    results.value = [];
    return;
  }
  const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`);
  results.value = await res.json();
});
</script>

Every keystroke fires a new request, and requests do not resolve in the order they were sent. If the request for v is slow and the request for vue is fast, vue's results land first and v's results land after, silently overwriting them. The callback did exactly what it was written to do; it just never asked "am I still the most recent run?"

That question is exactly what a watcher's cleanup mechanism answers. Getting there first requires being precise about what watch() and watchEffect() actually are.

The mental model: pull vs. push tracking

The mental model: watch() is told what to watch. watchEffect() discovers what to watch by running once and recording every reactive value it reads. Everything else — old/new values, laziness, immediacy — falls out of that one distinction.

watch(source, callback) takes an explicit source (a ref, a getter, a reactive() object, or an array of them) and a callback. It does not run on creation by default. It runs only when the named source changes, and it hands the callback both the new and the old value.
watchEffect(fn) takes a single function with no separate source. It runs immediately, once, synchronously (well — see flush timing below) to figure out what it read, and re-runs itself in full whenever any of those dependencies change. There is no "old value" concept, because there's no fixed source to diff against — the whole function reruns.

Put differently: watch is a subscription to a specific address. watchEffect is a subscription to whatever addresses this function happens to visit today — and it can visit different addresses on different runs, exactly like a computed() getter does. The dependency-tracking mechanism (a run records every reactive value it reads) is shared across computed, watch's getter-form sources, and watchEffect alike.

Stage 1: the smallest watch()

import { ref, watch } from "vue";

const count = ref(0);

watch(count, (newVal, oldVal) => {
  console.log(`count went from ${oldVal} to ${newVal}`);
});

count.value++; // logs: "count went from 0 to 1"

Key concept: the callback did not run when watch was declared — only after count changed. That's the "lazy by default" behavior, and it's the first thing that trips people up coming from watchEffect.

Stage 2: the same job with watchEffect()

import { ref, watchEffect } from "vue";

const count = ref(0);

watchEffect(() => {
  console.log(`count is now ${count.value}`);
});
// logs immediately: "count is now 0"

count.value++; // logs: "count is now 1"

Key concept: watchEffect ran once immediately, on creation, before anything changed — because it has to run once just to discover that count is a dependency. watch never needed to run to know its source; you named it.

If the job is "sync this state to something external, right now and on every future change" — a document title, a localStorage key, an analytics call — watchEffect is usually the shorter answer. Need the old value, or need to stay silent until one specific thing changes? Reach for watch.

Stage 3: multiple sources, and watching inside an object

watch accepts an array of sources, and hands the callback matching arrays of new/old values:

watch([firstName, lastName], ([newFirst, newLast], [oldFirst, oldLast]) => {
  console.log(`${oldFirst} ${oldLast} -> ${newFirst} ${newLast}`);
});

Watching a single property of a reactive() object requires a getter function, not the bare property — because reactive().someProp is just a plain value the instant you read it out of the object, with no reference back to the proxy:

const state = reactive({ count: 0, name: "vue" });

// Wrong: this is a snapshot number, not a reactive source.
// watch(state.count, cb) never fires.

// Correct: a getter re-reads the proxy every time Vue checks it.
watch(
  () => state.count,
  (newCount, oldCount) => console.log(newCount, oldCount)
);

This is the same "reactivity is a subscription made at read time" rule from the ref vs reactive article — watch needs something it can re-read, and a getter is how you hand it that.

Stage 4: immediate, deep, and once

Three options on watch change when and how often it fires (watchEffect accepts only flush, covered next, plus the dev-only onTrack/onTrigger — it runs on creation and tracks everything it reads, so immediate, deep and once don't apply):

watch(source, callback, {
  immediate: true, // also run once, right away, with oldValue undefined
  deep: true,      // walk the whole object/array, not just the top-level reference
  once: true,      // (Vue 3.4+) auto-stop after the callback fires the first time
});

deep: true is the one to use sparingly. Watching a getter that returns an object (() => state.someObject) or a ref holding one only fires when the whole object is replaced (a reactive() object passed directly is already implicitly deep); deep walks every nested property so a change three levels down also fires — at the cost of Vue actually traversing the structure to set that tracking up. On a large or deeply nested object, that traversal is real work.

Stage 5: flush timing — pre, post, sync

Both watch and watchEffect accept flush, and it answers a different question than the options above: relative to a component's own re-render, when does this callback run?

`flush` value	When it runs	Default?
`'pre'`	Before the component re-renders	Yes, for both APIs
`'post'`	After the component has re-rendered and the DOM is updated	No
`'sync'`	Synchronously, the instant the dependency is written	No

This connects directly to the batching behavior from Vue nextTick Explained: a pre-flush watcher (the default) can run before the DOM reflects the change that triggered it. If your callback needs to measure or read an element that just changed size or content, flush: 'pre' will read stale layout:

watch(
  items,
  () => {
    // With the default 'pre' flush, the DOM here may not yet
    // reflect the new `items` — this measurement can be one step behind.
    console.log(listRef.value.scrollHeight);
  },
  { flush: "post" } // wait for the DOM update first
);

flush: 'sync' skips Vue's batching queue entirely and runs the instant the dependency is written — useful for invalidating an external cache the moment something changes, but dangerous on sources mutated many times synchronously (e.g. an array filled in a loop), since it fires on every single mutation with no batching.

Stage 6: cleanup and the race condition, fixed

Back to the search box. The fix is to give each run a way to say "abort me if a newer run has already started" — and both watch and watchEffect give you exactly that, as onWatcherCleanup() (3.5+), which must be called synchronously during the callback (before any await):

<script setup>
import { ref, watch, onWatcherCleanup } from "vue"; // onWatcherCleanup: Vue 3.5+

const query = ref("");
const results = ref([]);

watch(query, async (q) => {
  if (!q) {
    results.value = [];
    return;
  }

  const controller = new AbortController();
  onWatcherCleanup(() => controller.abort());

  try {
    const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`, {
      signal: controller.signal,
    });
    results.value = await res.json();
  } catch (e) {
    if (e.name !== "AbortError") throw e; // an aborted run is expected, not an error
  }
});
</script>

Key concept: onWatcherCleanup registers a function that Vue calls right before the next run of this same watcher — and also when the component unmounts. Type vue, and the moment the e keystroke starts a new run, the previous run's cleanup fires first, aborting its in-flight fetch. An aborted request rejects with an AbortError instead of resolving, so it can never reach results.value — and the try/catch swallows just that expected rejection, which would otherwise surface through Vue's error handler on every superseded keystroke. Order of arrival stops mattering, because only the current, un-aborted request is allowed to write.

The same mechanism is also passed as the callback's third parameter (the only option before 3.5, and still supported):

watch(query, async (q, oldQ, onCleanup) => {
  const controller = new AbortController();
  onCleanup(() => controller.abort());
  // ...
});

The two forms differ here: onWatcherCleanup must be called before the first await — after it, Vue can't tell which watcher run it belongs to, so dev mode warns and the cleanup is silently dropped. The onCleanup argument is bound to its watcher, so it isn't subject to that constraint.

Stopping a watcher

Both watch and watchEffect return a handle — call it (or .stop()) to stop; since 3.5 it also has .pause() / .resume():

const stop = watchEffect(() => {
  console.log(count.value);
});

stop(); // this effect will never run again

You rarely need to call this yourself inside a component: a watcher created synchronously during setup() or <script setup> is automatically stopped when the component unmounts; one created later from an async callback (a setTimeout, a .then) inside that same <script setup> is not. You need the manual stop() mostly for watchers created outside a component's setup — inside a composable that runs after mount, in a store, or in plain JS — where Vue has no unmount to tie it to.

Edge cases and gotchas

await breaks dependency discovery. watchEffect only tracks reads that happen synchronously before the first await. Anything read after an await inside the function is invisible to it and will not trigger a re-run if it changes.
A getter that reads nothing reactive never fires. watch(() => someObj.plainProperty, cb) looks correct but never runs if plainProperty isn't itself reactive — there's nothing for Vue to subscribe to.
watchEffect can over-track. Because it tracks everything the function body reads, a large conditional inside it can pick up dependencies you didn't intend, causing extra re-runs. watch with an explicit source avoids this by construction.
.push/.splice fire a non-deep watcher only when the source is the reactive() array itself (implicitly deep). watch(itemsRef, cb) on a ref([]), or a getter like () => state.items, tracks only the array reference — in-place mutations need deep: true, or watch () => items.value.length.
immediate: true hands undefined as oldValue on that first synthetic run (an empty array [] when watching an array of sources) — always guard against it if the callback compares old and new.

Best practices

Reach for watchEffect when the job is "keep this side effect in sync with whatever it reads" and you don't need the old value — document titles, localStorage, imperative DOM syncing.
Reach for watch when you need the previous value, need the callback to stay silent until one specific thing changes (not everything the function happens to read), or want lazy behavior by default.
Default to flush: 'pre' (the default) unless the callback reads the DOM — then use 'post'. Reserve 'sync' for cache-invalidation-style work that must happen before Vue's own batching, and never on a source that's mutated many times in one tick, like an array.
Always pair an async watcher with cleanup the moment more than one run can be in flight at once — a search box, a resource fetched by an ID prop, anything driven by fast user input.
Avoid deep: true on large objects if you can watch a specific derived getter instead; the traversal cost is real.

FAQ

Does watchEffect run on component mount?

It runs when it's created — during setup(), before mount — synchronously with the default flush: 'pre'; with flush: 'post' (watchPostEffect) even the first run waits until after render. That first run is also how it discovers its dependencies.

What's the difference between watch's deep option and watchEffect?

They're unrelated axes. deep controls how far into a reactive object watch traverses to detect a change. watchEffect always tracks only what it actually reads during a run, deep or shallow, because it has no fixed source to traverse — it just doesn't re-read nested properties unless your function body does.

Why isn't my watch callback firing when I mutate a reactive object property?

The most common cause is watching a plain snapshot instead of a getter — see Stage 3. The second most common cause is watching a ref holding an object and mutating a nested property without deep: true (the object is reactive, but watch(ref) only tracks .value); the ref's own .value reference hasn't changed, so a shallow watch sees nothing.

How do I stop a watcher manually?

Call the function watch/watchEffect returns: const stop = watch(...); stop();. For a watcher created synchronously inside <script setup>, you rarely need to — unmount does it for you.

Is watchEffect the same as a computed?

No. computed() returns a cached value meant to be read elsewhere and must stay pure (no side effects). watchEffect runs a side effect and returns nothing meant to be read — it's for doing something, not deriving something.

Does watch support async callbacks?

Yes — async (newVal, oldVal) => { ... } works exactly as shown above. Just remember that oldVal and newVal are captured before the await, and that any onWatcherCleanup() call must happen before the first await.

Cheat sheet

import { ref, reactive, watch, watchEffect, onWatcherCleanup } from "vue";

// watch(): explicit source, lazy by default, gives old + new value
watch(source, (newVal, oldVal) => { /* ... */ });
watch([a, b], ([newA, newB], [oldA, oldB]) => { /* ... */ });
watch(() => reactiveObj.prop, (newVal, oldVal) => { /* ... */ }); // getter for a nested property

// watchEffect(): auto-tracked, runs immediately, no old value
watchEffect(() => { document.title = title.value; });

// Options (watch only, except flush which both accept)
watch(source, cb, {
  immediate: true, // also run once immediately (oldValue is undefined that time)
  deep: true,      // traverse nested properties, not just the top reference
  once: true,      // Vue 3.4+: auto-stop after first fire
  flush: "post",   // 'pre' (default) | 'post' (after DOM update) | 'sync' (no batching)
});

// Cleanup: cancel a stale async run before the next one starts (Vue 3.5+)
watch(source, async (val) => {
  const controller = new AbortController();
  onWatcherCleanup(() => controller.abort()); // before the first await
  try {
    await fetch(url, { signal: controller.signal });
  } catch (e) {
    if (e.name !== "AbortError") throw e;
  }
});

// Stopping
const stop = watchEffect(() => { /* ... */ });
stop(); // manual — usually unnecessary for watchers created synchronously in <script setup>, which auto-stop on unmount
// Vue 3.5+: the handle also has stop.pause() / stop.resume()

Key takeaways

watch is told its source explicitly and is lazy by default; watchEffect discovers its sources by running once, immediately, and re-runs the whole function when any of them change.
flush decides when relative to the DOM update — 'pre' (default) can run before a DOM change, 'post' waits for it, 'sync' skips batching entirely.
onWatcherCleanup (Vue 3.5+) — or the callback's third onCleanup argument, the only option on earlier versions — fires right before the next run, which is exactly what stops a slow, stale async response from overwriting a fresher one.
A watcher created synchronously in <script setup> stops itself on unmount; one created outside a component's setup needs its returned stop() called by hand.

The search box from the top of this article isn't really a search-box bug — it's what happens any time a watcher's previous run outlives its next run and nobody told it to stop. Once cleanup is a habit rather than an afterthought, that entire category of bug stops happening. What's the last race condition you tracked down that turned out to be a missing cleanup? 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 9-question quiz →

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

📚 Read next

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

Thanks for reading! Let's stay connected:

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

I Shipped a Fix. My Service Worker Kept Serving the Bug.

Parsa Jiravand — Mon, 12 Oct 2026 06:10:22 +0000

Three days after a critical fix went live, the support queue still had tickets coming in — all describing the exact bug you'd already closed. Every reply said the same thing: "I refreshed, it's still broken." A few said they'd refreshed twice.

You pull up the deployed bundle. The fix is there, served from the server, timestamped correctly. You open the site in an incognito window and it works. You open it in your own regular browser, the one you've had open all week, and there's the bug — your bug, the one you already fixed, running code from four days ago.

Nothing about your deploy was wrong. The thing lying to your users was sitting in their browser, and it was doing exactly what you told it to do.

The obvious fix that doesn't fix it

The instinct is "tell them to hard-refresh." Ctrl+Shift+R, clear cache, the works. It helps some of your users and does nothing for the rest, because a service worker isn't the browser's HTTP cache — it's a script that intercepts every fetch on your origin and decides, in your code, what to answer with. A normal reload doesn't bypass it. A hard refresh sometimes does, depending on browser and whether the service worker itself is also cached. Telling users to fight their own browser is not a fix; it's a workaround you're asking thousands of people to perform by hand, repeatedly, every time you ship.

The real question isn't "how do we get users to clear their cache." It's "why didn't the new version take over automatically" — and that's a lifecycle question, not a caching question.

What's actually happening

A cache-first strategy looks like this, and it's genuinely the right choice for a lot of assets:

self.addEventListener("fetch", (event) => {
  event.respondWith(
    caches.match(event.request).then((cached) => cached || fetch(event.request))
  );
});

Check the cache. If it's there, serve it — no network round trip, instant response, works offline. That's the entire appeal of a service worker for a performance-conscious team, and it's why this pattern shows up in so many tutorials. The trap is what "cache-first" means for the one file that tells the browser everything else changed: if index.html or your main JS bundle is cache-first too, the browser never even asks the network whether a new version exists. It's handed the old answer before the question can be asked.

So you deploy a new service worker with a fix for this — and it still doesn't help, for a second, separate reason: a new service worker doesn't take over the instant it's installed. The lifecycle is install → waiting → activate, and by design, a waiting service worker sits idle as long as any tab is still controlled by the old one. Your users don't close all their tabs. Some of them haven't closed that tab since Monday. So the new worker waits, and waits, and the old one keeps answering every request with cache-first confidence.

🎮 Try it yourself

▶️ Open the interactive playground →

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

The two lines that actually fix it

Getting a new version to take over immediately is two separate opt-ins, and skipping either one leaves the bug half-fixed:

self.addEventListener("install", (event) => {
  event.waitUntil(self.skipWaiting()); // don't wait for old tabs to close
});

self.addEventListener("activate", (event) => {
  event.waitUntil(clients.claim()); // take control of open tabs right now
});

skipWaiting() moves the new worker out of "waiting" the moment it finishes installing, instead of parking until every old tab closes. clients.claim() is the other half: without it, a freshly-activated worker still only controls tabs that load after it activates — any tab that was already open keeps talking to whichever worker controlled it when it loaded. Call both, and a currently-open tab's very next fetch is answered by the new worker.

That solves "the new version never takes over." It doesn't solve the first problem — a cache-first index.html or main bundle will still serve whatever that new worker finds in its cache, and if the install step cached the old files before the fetch handler takes over, you've just made the stale response arrive faster. The fix there is matching the strategy to the file:

HTML and anything that names your entry bundle — network-first, or no caching at all. These are cheap to fetch and they're the one place "slightly stale" becomes "actively wrong."
Fingerprinted, hashed assets (app.a3f91c.js) — cache-first is correct and free. The filename changes when the content does, so there's no staleness to worry about; the old file and the new file are simply different URLs.
Everything in between (an API response, a non-hashed icon) — stale-while-revalidate: answer instantly from cache, and kick off a network fetch in the background that updates the cache for next time.

const CACHE_NAME = "app-cache-v7"; // bump this every deploy

self.addEventListener("activate", (event) => {
  event.waitUntil(
    caches.keys().then((keys) =>
      Promise.all(keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k)))
    )
  );
});

That version bump is the detail cache-first tutorials leave out most often. Called the way the fetch handler above calls it — with no cacheName option — caches.match() doesn't just check the cache you're currently writing to; it searches every cache under your origin, oldest first, and returns the first match it finds. Skip the activate-handler cleanup and a stale, un-deleted app-cache-v6 can still win that search over the app-cache-v7 entry sitting right next to it, even though the newer cache already has the file you just deployed. Deleting the old cache on activate isn't just tidiness — it's what guarantees caches.match() has nothing stale left to find.

Why this isn't a service worker bug

None of this is the API misbehaving. A service worker that keeps serving cached content after a deploy is doing precisely what cache-first plus "wait for every tab to close" plus "never evict the old cache" adds up to. The lifecycle exists so a new version can't yank state out from under a tab mid-interaction — that's the feature, not an oversight. The bug is in treating "cache it" as a complete caching strategy, when the strategy actually has three separate knobs: what gets cached, when the new worker takes over, and when the old cache gets deleted. Ship a fix to only one of those and the other two will happily keep serving yesterday's bug to someone who is absolutely certain they refreshed.

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

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

Next time a user says "I refreshed and it's still broken," the first question isn't "did you refresh hard enough." It's which of your three knobs you forgot to turn.

What's the longest a stale deploy has haunted one of your users before someone thought to check the service worker?

📚 Read next

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

Thanks for reading! Let's stay connected:

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

Nuxt 4 Migration: The Breaking Changes That Actually Bite

Parsa Jiravand — Sun, 11 Oct 2026 12:26:26 +0000

Nuxt 3 reached end-of-life on July 31, 2026. No more security patches, no more bug fixes, no more compatibility updates — ever, for that line. If your package.json still says "nuxt": "^3", you're not behind on a nice-to-have; you're running unmaintained software in production. And the first time you run npm install nuxt@latest to fix that, something you didn't touch will break in a way the error message doesn't explain.

This article is written against Nuxt 4.6.0 (verified against the nuxt package's npm dist-tags in October 2026 — the 3x tag is frozen at 3.21.11, a patch that actually shipped August 5, 2026, five days after the cutoff; the last release before the cutoff itself was 3.21.10, on July 27, 2026). It walks through what the official Nuxt 4 release notes and upgrade guide actually say breaks, why those specific things were chosen to break, and the staged path that lets you fix each one without a single big-bang rewrite.

What you'll learn

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

Explain why Nuxt 4 defaults to an app/ directory instead of treating it as cosmetic churn
Identify the exact conditions under which the new "Singleton Data Fetching Layer" breaks a useAsyncData/useFetch call that worked fine on Nuxt 3
Fix the null → undefined default change before it silently passes a stale if (data.value === null) check
Use future.compatibilityVersion: 4 to surface every breaking change while your app is still running on the Nuxt 3 package
Run the official codemod instead of hand-editing import paths across a whole codebase

Who this is for

You have a Nuxt 3 app in production, or you're planning a new one and want to know what "Nuxt 4" actually changes before you commit to it. You don't need prior Nitro or Nuxt-internals knowledge — just familiarity with useAsyncData/useFetch and a standard nuxt.config.ts.

The problem: the upgrade that isn't a patch bump
The mental model: Nuxt 4 is about boundaries, not folders
Stage 1: the directory default, and why back-compat usually saves you
Stage 2: the Singleton Data Fetching Layer
Stage 3: null becomes undefined, and shallowRef replaces ref
Stage 4: the window.NUXT removal and the TypeScript surprise
Stage 5: the staged migration path
Edge cases and gotchas
Best practices
FAQ
Cheat sheet
Key takeaways

The problem: the upgrade that isn't a patch bump

Here's the instinct that gets people in trouble: Nuxt 3 minor versions have been safe to bump for years, so nuxt@4 looks like just the next number in the same sequence. A team runs the upgrade on a Friday afternoon, the dev server boots, the homepage renders, and it ships.

Monday morning, two unrelated bugs show up:

// A composable that worked for a year
const { data: user } = useAsyncData('current-user', () => $fetch('/api/me'))

// ...later, in a completely different component:
if (user.value === null) {
  // this branch used to run before the fetch resolved — now it never does
  showGuestBanner()
}

The guest banner stops appearing for logged-out users on first paint. Nobody touched useAsyncData. Nobody touched the banner component. The bug is two features away from the code that actually changed, because data now defaults to undefined, not null — and undefined === null is false.

That's the shape of almost every Nuxt 4 migration bug: not a loud crash, a quiet behavioral default that moved. The fix for all of them is the same shape too — know the list, grep for it, fix it deliberately — which is what the rest of this article gives you.

The mental model: Nuxt 4 is about boundaries, not folders

The mental model: every headline Nuxt 4 change is Nuxt drawing a boundary it used to leave implicit, and then enforcing it. Nuxt 3 inferred almost everything from one root directory and a lot of convention; Nuxt 4 makes several of those conventions into contracts that tooling — the file watcher, the TypeScript project, the data layer — can actually rely on.

Once you see it that way, the "random" list of breaking changes stops being random:

The app/ directory isn't a cosmetic rename. It's Nuxt declaring "this subtree is the client application" so your file watcher can ignore node_modules/ and .git/ more aggressively, and your IDE can tell client code from server code by path alone.
The Singleton Data Fetching Layer isn't a performance tweak. It's Nuxt declaring "a key is one fetch, for real this time" — if two calls share a key, they now must agree on how that fetch behaves, because they're genuinely the same underlying state, not two independent calls that happen to collide.
The TypeScript changes aren't new bugs. They're Nuxt's project references finally being strict enough to surface type errors that were always there, just previously invisible to the compiler.

Read every section below through that lens: what boundary is this enforcing, and what breaks when my code quietly depended on that boundary being fuzzy?

Stage 1: the directory default, and why back-compat usually saves you

Nuxt 4's advertised headline change is that application code — components/, pages/, layouts/, app.vue — lives under app/ by default, while public/, shared/, server/, and nuxt.config.ts stay at the project root:

my-app/
├─ app/
│  ├─ app.vue
│  ├─ components/
│  └─ pages/
├─ server/
├─ public/
└─ nuxt.config.ts

Key concept: if your project already has this shape (most Nuxt 3 starters from the last year or two already do), nothing changes — Nuxt detects the existing layout and keeps it working. This is the part of the migration that generates the most noise online and causes the least real breakage.

Two situations where it does bite:

A custom srcDir. If you've set srcDir in nuxt.config.ts, Nuxt 4 resolves modules/, public/, shared/, and server/ from your project root instead of from that custom srcDir — the opposite of Nuxt 3's behavior. Override it explicitly with dir.modules, dir.public, and serverDir if you need the old resolution.
You want to keep the flat Nuxt 3 layout on purpose. Set srcDir: '.' together with dir.app in nuxt.config.ts, and nothing has to move.

If you do want to adopt the new layout, Nuxt ships a codemod rather than asking you to move files by hand:

npx codemod@latest nuxt/4/file-structure

Moving files is optional. Everything else in this article is not.

Stage 2: the Singleton Data Fetching Layer

This is the change most teams don't see coming, because it looks like useAsyncData just works differently now rather than looking like a documented breaking change.

In Nuxt 3, two useAsyncData/useFetch calls that happened to share a key were already treated as "the same fetch" in practice — the previous episode in this series covers exactly that sharing behavior and the auto-key bug it causes. Nuxt 4 takes that same-key-means-same-fetch idea and makes it a hard contract: calls sharing a key now must agree on handler, deep, transform, pick, getCachedData, serialize, default, and middleware. Mismatch any of them, and Nuxt logs a development-mode warning — but it doesn't block anything, and you still end up with inconsistent state instead of the two independent results you might expect:

// Component A
const { data } = useAsyncData('product-101', () => $fetch('/api/products/101'), {
  transform: (p) => ({ ...p, displayName: p.name.toUpperCase() }),
})

// Component B — same key, different transform
const { data } = useAsyncData('product-101', () => $fetch('/api/products/101'), {
  transform: (p) => p.name, // just the string
})
// Whichever call's options "win" depends on render order — this is the bug class.
// Nuxt warns about the mismatch in dev (a console warning, not a thrown error),
// but it doesn't stop the build and it doesn't fix the data — you still have to.

The fix: if two call sites legitimately need the same key, move the call into one shared composable so the options live in exactly one place, instead of being copy-pasted (and drifting) at each call site:

// app/composables/useProduct.ts
export function useProduct(id: string) {
  return useAsyncData(`product-${id}`, () => $fetch(`/api/products/${id}`), {
    transform: (p) => ({ ...p, displayName: p.name.toUpperCase() }),
  })
}

The other half of this change is getCachedData. It used to matter mostly on the initial load; in Nuxt 4 it's called on every fetch for that key — including a watch-triggered refetch or a manual refreshNuxtData() — and it receives a cause ('initial' | 'refresh:hook' | 'refresh:manual' | 'watch') so you can decide, per cause, whether to trust the cache:

const { data } = useAsyncData('dashboard-stats', () => $fetch('/api/stats'), {
  getCachedData(key, nuxtApp, ctx) {
    // Always skip the cache on a manual refresh — the whole point was to get fresh data.
    if (ctx.cause === 'refresh:manual') return undefined
    return nuxtApp.payload.data[key]
  },
})

Stage 3: null becomes undefined, and shallowRef replaces ref

Two smaller defaults sit next to the data layer change and are easy to miss in a changelog skim:

data and error now default to undefined, not null, when a fetch hasn't resolved yet or has no data. Grep your codebase for === null and !== null anywhere near a useAsyncData/useFetch result — every one of those is a candidate for the exact bug shown in "The problem" above.
data is now a shallowRef, not a deep ref. Mutating a nested property in place (data.value.items.push(x)) no longer triggers reactivity — you need to reassign data.value (or call refresh()) for the template to update. This trades a small amount of convenience for meaningfully better performance on large payloads, since Nuxt no longer has to deep-observe every field it fetches.

Both are one-line fixes once you know to look for them. Neither throws an error, which is exactly why they're worth grepping for deliberately rather than waiting for a bug report.

Stage 4: the window.NUXT removal and the TypeScript surprise

One small removal with a mechanical fix: window.__NUXT__ is removed after hydration completes, where it used to linger. Code reading it post-hydration (analytics scripts, debug snippets) needs to capture what it needs earlier — or read the same payload from useNuxtApp().payload instead, which Nuxt keeps around.

The bigger surprise isn't a removal at all, and it's opt-in rather than automatic: Nuxt 4 generates separate, context-specific TypeScript project references (tsconfig.app.json, tsconfig.server.json, tsconfig.node.json, tsconfig.shared.json) alongside the old merged tsconfig.json, and keeps the old one as the default for backwards compatibility — your existing root tsconfig.json keeps working, unchanged, until you point it at the new files. Once you do (a fresh Nuxt 4 project scaffolds it this way by default, and the migration codemod can set it up for an existing one), nuxt typecheck often jumps from zero errors to a page of them. That's not a new Nuxt 4 bug — each context now gets its own, more accurate globals and includes, so TypeScript can finally see code that was always slightly wrong.

Stage 5: the staged migration path

The official guide's real advice isn't "bump the package and fix what breaks" — it's to opt into Nuxt 4 behavior while still on the Nuxt 3 package, so you can fix issues one at a time with a fast feedback loop, before the cutover:

// nuxt.config.ts — still "nuxt": "^3.x" in package.json
export default defineNuxtConfig({
  future: {
    compatibilityVersion: 4,
  },
})

With that flag set, your Nuxt 3 app runs with Nuxt 4's new defaults — the data layer contract, the null/undefined change, the directory resolution — so you see every real breakage in your own code, in your own dev server, without touching your dependency tree yet. Fix what it surfaces, commit, then bump nuxt itself to ^4.0.0 as a final, much smaller step.

Run the migration recipe codemod once you're ready for the mechanical renames (pin the version — @latest has a known issue with this one):

npx codemod@0.18.7 nuxt/4/migration-recipe

Edge cases and gotchas

Module authors feel this hardest. Nuxt 2/Bridge support is fully removed from @nuxt/kit; check a module's own changelog for Nuxt 4 compatibility before upgrading an app that depends on it.
compatibilityDate needs bumping too. An old date pinned in nuxt.config.ts can keep you on legacy Nitro behavior even after the package upgrade.
Deep-mutating useAsyncData results in place is the most common silent breakage from the shallowRef change — the data changed, the UI just doesn't notice, which looks like an unrelated rendering bug.

Best practices

Flip future.compatibilityVersion: 4 before you touch the nuxt package version — the cheapest way to see your own breakage with the smallest blast radius.
Grep for === null / !== null near every useAsyncData/useFetch call before you upgrade, not after a bug report finds one for you.
Centralize any useAsyncData call two components legitimately share into one composable, so its options can't drift out of sync with the new matching requirement.
If you adopt the new project-references tsconfig.json (what a fresh Nuxt 4 project scaffolds, and what the migration codemod can set up for an existing one), run nuxt typecheck right away and treat what it surfaces as debt you already carried, not a new regression.
Don't move files into app/ as a first step. It's the lowest bug-to-effort part of this migration; the data layer and default-value changes are where real bugs hide.

FAQ

Do I have to move my files into the `app/` directory?

No. Nuxt 4 detects an existing Nuxt 3-style layout and keeps it working without any file moves. Moving to app/ is optional, and a codemod (npx codemod@latest nuxt/4/file-structure) does it for you if you choose to.

Will my app silently return wrong data after upgrading?

Only if two useAsyncData/useFetch calls share a key with mismatched options (transform, deep, pick, getCachedData, serialize, default, middleware, or the handler itself). Nuxt does log a development warning when it detects the mismatch, but it's a warning, not a thrown error — it doesn't stop the build, and the wrong data still ships unless you act on it. Centralizing shared-key calls into one composable removes the whole category of bug.

Is it safe to upgrade straight from an old Nuxt 3 version?

Yes, but the official guide's recommended path is to first set future.compatibilityVersion: 4 on your current Nuxt 3 app, fix everything it surfaces, and only then bump the nuxt package itself — rather than doing both at once.

What happens to Nuxt 3 apps that don't upgrade?

They keep running — npm packages don't disappear — but Nuxt 3 no longer receives security patches, bug fixes, or compatibility updates as of July 31, 2026. That risk grows, silently, the longer it's deferred.

Does this affect Nuxt modules I depend on, not just my own code?

Yes, independently of your own code. Nuxt 2/Bridge support is removed from @nuxt/kit, so a module that hasn't been updated for Nuxt 4 may break regardless of anything in this article. Check the module's own changelog before upgrading an app that relies on it.

Cheat sheet

Change	Old (Nuxt 3)	New (Nuxt 4)	What to do
App code location	flat `components/`, `pages/`, root `app.vue`	`app/components/`, `app/pages/`, `app/app.vue` (back-compat if unchanged)	Nothing required; `npx codemod@latest nuxt/4/file-structure` if you want to move
Shared `useAsyncData`/`useFetch` key	independent-feeling calls, loosely enforced	`handler`/`deep`/`transform`/`pick`/`getCachedData`/`serialize`/`default`/`middleware` must match	Centralize the call into one composable
`getCachedData`	mainly consulted on initial load	called on every fetch, receives `{ cause }`	Branch on `cause` to skip stale cache on manual refresh
`data`/`error` empty value	`null`	`undefined`	Replace `=== null` / `!== null` checks
`data` reactivity	deep `ref`	`shallowRef`	Reassign `data.value`, don't deep-mutate in place
`public/`/`assets/` server aliases	resolved	removed	Use explicit paths or asset imports
`window.__NUXT__`	present after hydration	removed after hydration	Read it before hydration completes, if you need it
Migration path	—	`future.compatibilityVersion: 4` on Nuxt 3, then bump the package	Fix issues with the dependency unchanged first

Key takeaways

Nuxt 3 reached end-of-life on July 31, 2026 — this migration is no longer optional maintenance, it's closing a real security gap.
The app/ directory default is backwards-compatible and rarely the thing that actually breaks; the data layer and default-value changes are.
useAsyncData/useFetch calls sharing a key now enforce matching options — centralize shared calls into one composable to guarantee it.
data/error default to undefined instead of null, and data is a shallowRef — both fail silently, not loudly, so grep for them rather than waiting for a bug report.
future.compatibilityVersion: 4 lets you fix every breaking change while still running the Nuxt 3 package, which is the official, lowest-risk path.

None of this is mysterious once you have the list — it's a short, specific set of boundaries Nuxt now enforces instead of leaving implicit. Run the compatibility flag, work the list once, and the actual package bump becomes the smallest, most boring step in the whole migration.

🎮 Try it yourself

▶️ Open the interactive playground →

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

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

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

What's the first thing on this list you'd find if you grepped your own app for it right now?

📚 Read next

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

Thanks for reading! Let's stay connected:

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

DEV Community: Parsa Jiravand

React 19.2 useEffectEvent: Why It Won't Fix Your Deps Array

What you'll learn

Who this is for

Table of contents

The problem: one dependency array, two different jobs

The mental model: reactive values vs. Effect Events

Stage 1 — the naive fix and its stale closure

Stage 2 — useEffectEvent, correctly

🎮 Try it yourself

Stage 3 — more than one Effect Event

Edge cases and gotchas

Best practices

FAQ

Is useEffectEvent a replacement for useCallback?

Can I call an Effect Event from a click handler?

Did this exist before React 19.2?

Does useEffectEvent need a special ESLint setup?

What happens if I put the Effect Event function in the dependency array anyway?

Cheat sheet

Key takeaways

🧠 Test yourself

📚 Read next

Inferred Type Predicates Won't Save filter(Boolean). Here's What Will.

The claim, and why it's believable

Try the one line everyone actually writes

Why the compiler can see one and not the other

🎮 Try it yourself

Why the mix-up happened

What to actually do with your type guards

The takeaway

🧠 Test yourself

Stop Letting One Widget Reflow the Whole Page. `contain` Scopes It.

The fix everyone reaches for first: throttle the JS

What's actually happening: layout has no boundaries by default

The fix: draw the boundary yourself

🎮 Try it yourself

The gotcha: size containment can collapse your element to nothing

When plain, uncontained CSS is still the right call

The takeaway

🧠 Test yourself

Stop Electing a Leader Tab. SharedWorker Just Holds the Connection.

The belief: something has to own the socket

The context that outlives every tab

🎮 Try it yourself

The puzzle this trades in

Browser support, honestly

No leader, no handoff, one quieter problem instead

🧠 Test yourself

📚 Read next

I Turned 44 Blog Posts Into a Frontend Roadmap You Have to Pass

What you'll learn

Who this is for

Table of contents

Why a frontend roadmap you tick yourself stops working

What people do today: seven frontend roadmaps and courses

Where today's options break

The mental model

Enter the Frontend Developer path

How the frontend roadmap works, in four steps

Step 1: the map

Step 2: a level is an article plus its quiz

Step 3: the checkpoint, and how to skip a stage

Step 4: your run, and the finish line

Under the hood: progress computed from quiz attempts

When not to use it

FAQ

Is this frontend roadmap really free?

Do I need an account to start the frontend roadmap?

How long does the frontend developer roadmap take?

Should I learn Vue or React first?

Can I skip HTML and CSS?

What happens if I fail a checkpoint?

Is the frontend developer certificate worth anything?

Cheat sheet: the path at a glance

Key takeaways

Remote work means someone else is telling your story for you

What's actually happening

So what do you actually do about it

Where this goes wrong

Is `useEffectEvent` a replacement for `useCallback`?

Does `useEffectEvent` need a special ESLint setup?

The gotcha: `size` containment can collapse your element to nothing

Stage 1 — what `priority` always did

Stage 3 — reaching past `preload` when you need more control

Does `quality={90}` throw an error in Next.js 16?

Why does hitting `/_next/image?...&q=90` directly return a 400 but the component doesn't error?

Is `priority` removed in Next.js 16?

Do I need to migrate `priority` to `preload` immediately?

Does `images.qualities` affect images served through a custom loader?