DEV Community: Parsa Jiravand

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___

Your Lighthouse Score Is 100. Long Animation Frames Explain the Jank.

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

Lighthouse says 100. CI is green. Then a support ticket comes in: "the filter button on the dashboard feels stuck for a second." You open the page yourself, click the same filter, and feel it too — a tiny freeze between the click and the list updating. Lighthouse never saw this, because Lighthouse scores page load. Nobody clicked anything during the audit.

This is the gap between "fast" and "doesn't feel fast": a single slow response to a single interaction, days after the page finished loading. The browser has had an API for this since 2017 — Long Tasks — and it has one deep flaw that makes it almost useless for exactly this kind of ticket.

The wrong way: squinting at a flame chart for a name that isn't there

Here's the instinctive move. Open DevTools, hit record, click the filter button, stop recording, and scrub through the Performance panel looking for the red-flagged block over 50ms.

You find it. It's purple, it's wide, and when you click it, the summary says:

Task
Duration: 187.00 ms

That's it. No function name you recognize — just "Task," sometimes attributed to a minified vendor chunk as (anonymous), sometimes split across three or four stacked calls that all blend into the same purple block. If the slow code lives in a third-party script (an analytics tag, a UI library, a chat widget), the browser won't even give you a stack — cross-origin scripts get stripped from the trace for privacy reasons, so the one task you actually care about is the one with the least information attached to it.

This is also exactly what the underlying longtask entry type gives you programmatically. It's not a DevTools limitation — the API itself reports a duration and almost nothing else:

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    console.log(entry.duration); // 187
    // ...and basically nothing else usable.
  }
}).observe({ type: "longtask", buffered: true });

You know that something took 187ms. You still don't know what. So the next move is usually wrapping suspiciously-large chunks of code in console.time/console.timeEnd and reloading, hoping you guessed the right function on the first try. On a codebase with more than one engineer, you rarely do.

The real diagnosis: the frame, not just the task

A dropped frame isn't only JavaScript. By the time the browser paints a frame, it ran your event handler, then recalculated style, then ran layout, then painted — and any one of those steps, or the hand-off between them, can be where the 187ms actually went. longtask only ever measured the "ran your event handler" part, as one undifferentiated blob.

The Long Animation Frames API (LoAF) reports on the whole frame instead, and names what happened inside it. Where it's supported, you observe "long-animation-frame" instead of "longtask":

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    console.log("frame duration:", entry.duration);
    console.log("blocked input for:", entry.blockingDuration);

    for (const script of entry.scripts) {
      console.log({
        invoker: script.invoker,       // e.g. "BUTTON#filter-btn.onclick"
        source: script.sourceURL,
        duration: script.duration,
        forcedLayout: script.forcedStyleAndLayoutDuration,
      });
    }
  }
}).observe({ type: "long-animation-frame", buffered: true });

Instead of one opaque "Task," each PerformanceLongAnimationFrameTiming entry hands you an array of PerformanceScriptTiming objects — one per script that ran during that frame, each with a duration, a sourceURL, and an invoker that names the actual handler ("BUTTON#filter-btn.onclick", not "anonymous"). It also exposes renderStart and styleAndLayoutStart, so you can see where the frame's time actually went: script execution, or the browser's own style/layout/paint work after your code handed off.

Run that observer against the filter-button ticket and the blob stops being a blob:

frame duration: 187
blocked input for: 134
{
  invoker: "BUTTON#filter-btn.onclick",
  source: "https://app.example.com/dashboard.js",
  duration: 162,
  forcedLayout: 71
}

forcedStyleAndLayoutDuration: 71 is the tell. That's time spent on forced layout — reading a layout-dependent property like offsetHeight right after writing to the DOM, which makes the browser stop and recalculate synchronously instead of waiting for its normal paint schedule. The click handler wasn't slow because the filter logic was heavy; it was slow because it wrote to the DOM, then immediately read a size back from it, in a loop, once per filtered row.

The fix, once you know what you're fixing

Knowing the handler's name and that 71 of its 162ms went to forced layout turns a guessing game into a code review. The fix here is the standard one for layout thrash: stop interleaving reads and writes. Batch every DOM write first, then read sizes once, after:

// before: read-write-read-write, once per row — forces layout every iteration
rows.forEach((row) => {
  row.style.height = computeHeight(row);
  totalHeight += row.offsetHeight; // forces a synchronous layout recalculation
});

// after: write everything, then read everything, once
rows.forEach((row) => {
  row.style.height = computeHeight(row);
});
totalHeight = rows.reduce((sum, row) => sum + row.offsetHeight, 0);

Re-run the observer and forcedStyleAndLayoutDuration on that entry drops to near zero, because there's no longer a read sandwiched between writes forcing the browser to recompute layout mid-loop. The frame still does the same amount of work — it just stops forcing the browser to do that work twice.

Why this matters beyond one button

This isn't a one-off diagnostic trick. Interaction to Next Paint (INP) — the Core Web Vital that replaced First Input Delay — measures exactly the gap between a user's interaction and the frame that responds to it. A long animation frame that overlaps a click, keypress, or tap is, by definition, the thing making your INP score worse. blockingDuration on a LoAF entry is close kin to what's slowing that metric down, which is why the Chrome team built this API specifically to make INP regressions debuggable in production, not just in a local DevTools session you happened to be recording at the right moment.

The honest caveat

The Long Animation Frames API shipped in Chrome and Edge 123 (March 2024), after an origin trial — Firefox and Safari don't implement it yet, and there's no public commitment on when or whether they will. If your users are meaningfully split across browsers, you're diagnosing the Chromium slice of your traffic, not all of it. Feature-detect before you rely on it:

if (PerformanceObserver.supportedEntryTypes.includes("long-animation-frame")) {
  // use LoAF
} else if (PerformanceObserver.supportedEntryTypes.includes("longtask")) {
  // fall back to duration-only longtask — better than nothing
}

That's a real gap, not a footnote to skip past. But for the browser where it does exist, it turns "something took 187ms" into "this handler forced layout 71 of those milliseconds, here's the file" — which is the difference between a ticket you can act on and one you close as "couldn't reproduce."

🎮 Try it yourself

▶️ Open the interactive playground →

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

Next time a user says a page "just feels slow" and your Lighthouse score says otherwise, open the console and observe long-animation-frame before you touch the Performance panel. What's the slowest interaction on your own site right now — and do you already know, without looking, which handler it's going to name?

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

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

📚 Read next

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

Thanks for reading! Let's stay connected:

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

React 19.3 Fragment Refs: Skip the Wrapper Div for a Ref

Parsa Jiravand — Sat, 10 Oct 2026 12:12:30 +0000

You're building a dashboard. Three stat cards need to render as siblings inside a CSS grid that expects each one to land in its own column — and you need a single ref on the group of three, so an IntersectionObserver can tell you when the cluster scrolls into view. There's no component boundary to hang that ref on, so you reach for the oldest trick in the book: wrap the three cards in a <div>.

The grid breaks. Your three cards, each meant to be its own grid item, are now squashed inside the one cell the wrapper <div> occupies.

React 19.3 (released September 9, 2026) ships a direct fix for this: a ref on a <Fragment>. No wrapper, no extra DOM node, and a real object back — a FragmentInstance — that can do more than a typical element ref ever could. This article covers what Fragment Refs actually are, the exact API you get, and the restrictions that will bite you if you don't know about them up front.

This article is written against React 19.3.0 (verified against the current npm latest dist-tag and the official React blog's 19.3 release post) and assumes React 19-era function components and hooks throughout. Fragment Refs are a DOM-rendering feature, so they need react-dom 19.3 or later alongside react 19.3 or later.

What you'll learn

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

Explain exactly why a wrapper <div> added only to hold a ref is a real structural change, not a free one
Attach a ref to a <Fragment> and read what comes back — a FragmentInstance, not a DOM node
Use the FragmentInstance methods that act on a sibling group as a unit: addEventListener, observeUsing, focus/focusLast, getClientRects, scrollIntoView
Tell which methods only see first-level DOM children and which search every nested child, so you don't get a silent no-op
Decide when a Fragment Ref is the right tool and when a real wrapper element still is

Who this is for

You've called useRef to grab a DOM node, and you've written a wrapper <div> at least once for no reason other than "something needs to hold the ref." No class components or Server Components knowledge required.

The problem: a ref has nowhere to live
The mental model
Stage 1: a ref on a Fragment
Stage 2: group-level event listening
Stage 3: observing the group with observeUsing
Stage 4: focus management across the group
Stage 5: measuring and scrolling the group
Edge cases and gotchas
Best practices: when to reach for this
FAQ
Cheat sheet
Key takeaways

The problem: a ref has nowhere to live

Here's the dashboard component, written the way most of us would write it before 19.3:

// The wrong way first: wrap the group just to hold a ref.
function StatGroup({ stats }) {
  const groupRef = useRef(null);

  useEffect(() => {
    const observer = new IntersectionObserver(([entry]) => {
      console.log("group visible:", entry.isIntersecting);
    });
    observer.observe(groupRef.current);
    return () => observer.disconnect();
  }, []);

  return (
    <div ref={groupRef} className="stat-group">
      {stats.map((s) => (
        <StatCard key={s.id} {...s} />
      ))}
    </div>
  );
}

That <div className="stat-group"> is the only reason this code compiles — useRef needs a real DOM node to attach to, and a plain <>...</> fragment can't take a ref. But the parent that renders <StatGroup /> is a CSS grid:

.dashboard {
  display: grid;
  grid-template-columns: repeat(6, 1fr);
  gap: 12px;
}

It expects every stat card to be its own grid item, interleaved with other dashboard widgets. Instead, the wrapper <div> becomes one grid item — the three cards it contains collapse into that single cell instead of occupying three. You can reach for display: contents on the wrapper to make it disappear from layout, but that has its own cost: Safari has shipped multiple bugs around display: contents and focus/accessibility trees, and the node still shows up in :nth-child counts and querySelector results in the parent — it just doesn't participate visually. You've traded a layout bug for an invisible structural one.

The real problem isn't the IntersectionObserver call. It's that the only way to get a ref has always been to add a DOM node, whether or not your layout wanted one.

The mental model

The mental model: a Fragment has never rendered a DOM node — that's its entire purpose, grouping children for React's own bookkeeping without touching the real DOM tree. A ref on a Fragment doesn't change that. What changes is that React now hands you a FragmentInstance: a stable object that knows which real DOM nodes belong to this group and can act on all of them as a unit.

Think of it less like a new element you could select with CSS, and more like a remote control for "all the first-level DOM children of this Fragment." You press a button on the remote (addEventListener, observeUsing, focus) and it reaches every child in the group — but it never adds a node for the remote itself to live on.

Stage 1: a ref on a Fragment

The <>...</> shorthand can't take a ref — you have to import Fragment explicitly:

import { Fragment, useRef, useEffect } from "react";

function StatGroup({ stats }) {
  const groupRef = useRef(null);

  useEffect(() => {
    console.log(groupRef.current); // a FragmentInstance, not a DOM node
  }, []);

  return (
    <Fragment ref={groupRef}>
      {stats.map((s) => (
        <StatCard key={s.id} {...s} />
      ))}
    </Fragment>
  );
}

Key concept: groupRef.current is now a FragmentInstance object. There is still zero extra DOM in the tree — the three StatCard elements render as direct grid children exactly as if StatGroup didn't exist at all.

Stage 2: group-level event listening

A FragmentInstance exposes addEventListener, removeEventListener, and dispatchEvent — but they attach to every first-level DOM child of the Fragment, not to a single node:

useEffect(() => {
  const instance = groupRef.current;
  const onClick = (e) => console.log("clicked inside the group:", e.target);
  instance.addEventListener("click", onClick);
  return () => instance.removeEventListener("click", onClick);
}, []);

Key concept: this is one listener call standing in for "a listener on each of the three cards," without ever touching StatCard's own code. That's the real payoff for a library component that doesn't want to force every consumer to wire up delegation by hand.

Stage 3: observing the group with observeUsing

This is the method that solves the dashboard problem from the top of the article — a real IntersectionObserver, pointed at the whole group, with no wrapper node to observe:

useEffect(() => {
  const instance = groupRef.current;
  const observer = new IntersectionObserver(([entry]) => {
    setVisible(entry.isIntersecting);
  });
  instance.observeUsing(observer);
  return () => instance.unobserveUsing(observer);
}, []);

observeUsing accepts either an IntersectionObserver or a ResizeObserver and attaches it to every first-level DOM child — React handles fanning the single observer out to all three cards and reporting back.

Key concept: the grid from the opening example is now untouched. All three StatCards are direct grid items, and the observer still fires on the group as a whole.

Stage 4: focus management across the group

focus() and focusLast() behave differently from the methods above — they search all nested children, depth-first, not just the first level:

function Toolbar({ children }) {
  const groupRef = useRef(null);
  return (
    <>
      <button onClick={() => groupRef.current.focus()}>Skip to toolbar</button>
      <Fragment ref={groupRef}>{children}</Fragment>
    </>
  );
}

focus() walks into however deeply nested the real focusable element is — a <button> three components down still gets found — and moves focus there. blur() removes focus from the active element, but only if that element is currently inside the Fragment; otherwise it's a no-op.

Key concept: this is the one family of methods that doesn't share the "first-level only" restriction the rest of the API has. Don't assume the restriction below applies uniformly — it doesn't.

Stage 5: measuring and scrolling the group

getClientRects() returns a flat array of DOMRects — one or more per first-level child — so you can measure a sibling group as a unit without a wrapper to call getBoundingClientRect() on:

const rects = groupRef.current.getClientRects();
const totalWidth = Math.max(...rects.map((r) => r.right)) - Math.min(...rects.map((r) => r.left));

scrollIntoView(alignToTop?) scrolls the group's children into view — but its signature is narrower than the DOM method of the same name on a normal element:

groupRef.current.scrollIntoView();      // scrolls the first child to the top
groupRef.current.scrollIntoView(false); // scrolls the last child to the bottom
groupRef.current.scrollIntoView({ behavior: "smooth" }); // throws — see below

Edge cases and gotchas

Most methods only see first-level DOM children. addEventListener, observeUsing, and getClientRects operate on the first real DOM nodes React finds walking down from the Fragment — through any nested components or fragments in between, but stopping the instant it hits an actual DOM element. If one of those children itself wraps more DOM (say, a <Badge> that renders <div><span>…</span></div>), the inner <span> is one level too deep for a direct attachment — though a real click on it still bubbles up through the DOM to the <div> as normal, unless something calls stopPropagation() along the way.
focus/focusLast are the exception — they search every nested child depth-first, specifically because "find the first focusable thing in this group" needs to look arbitrarily deep.
observeUsing doesn't work on text nodes. If the Fragment's only children are text, React logs a development warning rather than silently doing nothing.
scrollIntoView takes a boolean, not an options object. Passing { behavior: "smooth" } the way you would to a DOM element's scrollIntoView throws an error — this is the one gotcha most likely to surface in code review, because the two APIs share a name but not a signature.
Hidden Activity trees don't receive fragment listeners. If the group is inside a hidden Activity boundary, addEventListener calls don't apply until the boundary becomes visible, at which point React applies them automatically.
You cannot use the <>...</> shorthand. Passing ref to the shorthand form isn't supported; you must import { Fragment } from "react" and write <Fragment ref={...}> explicitly. It's an easy habit to break, since the shorthand is the default almost everywhere else in a modern codebase.

Best practices: when to reach for this

Reach for a Fragment Ref when a component renders a sibling group it doesn't want to visually wrap — a list's items, a group of grid cells, children of a component whose caller controls the surrounding layout — and the group still needs group-level DOM capability: delegated events, one IntersectionObserver/ResizeObserver, keyboard-focus entry, or a combined bounding measurement.

Don't reach for it when the group itself needs actual styling — a background, a border, padding around the whole cluster. A Fragment still renders nothing to the DOM, so there's nothing there for CSS to select. That case genuinely needs a real wrapper element; a Fragment Ref isn't a style-free wrapper, it's a ref-only one.

Don't reach for it for a single child, either — just put the ref directly on that one element. The whole feature exists for the group case a single ref never covered.

FAQ

Can I pass a ref to the `<>...</>` shorthand?

No. React requires the explicit form — import { Fragment } from "react" and <Fragment ref={yourRef}>...</Fragment> — specifically so the shorthand stays free of the extra import for the common case that doesn't need a ref.

Does a Fragment Ref add anything to the DOM?

No. The FragmentInstance operates on the children's real DOM nodes as a group, without changing that DOM's structure at all. If you inspect the page, there's no new element — the children render exactly where they would without the ref.

Will a click on a deeply nested element still reach a Fragment's addEventListener?

Only if nothing stops it from bubbling. The listener attaches directly to the first real DOM element React finds under each child — not to anything nested one DOM level deeper inside that child's own markup. A plain DOM click event still bubbles upward in the usual way, so it typically reaches the attachment point regardless, unless an intervening handler calls stopPropagation().

Do I need anything beyond react-dom 19.3?

No extra package. Fragment Refs ship as part of react and react-dom 19.3.0 together — there's no separate opt-in flag.

Does the React Compiler change how Fragment Refs behave?

No. The compiler auto-memoizes component output based on the Rules of React; it doesn't touch ref semantics. A FragmentInstance behaves identically whether or not the component that creates it is compiled.

Cheat sheet

import { Fragment, useRef, useEffect } from "react";

function Group({ children }) {
  const ref = useRef(null); // ref.current → a FragmentInstance

  useEffect(() => {
    const instance = ref.current;

    // Group-level click delegation (first-level DOM children only)
    const onClick = (e) => {/* ... */};
    instance.addEventListener("click", onClick);

    // One observer for the whole group (IntersectionObserver or ResizeObserver)
    const observer = new IntersectionObserver(/* ... */);
    instance.observeUsing(observer);

    return () => {
      instance.removeEventListener("click", onClick);
      instance.unobserveUsing(observer);
    };
  }, []);

  return <Fragment ref={ref}>{children}</Fragment>;
}

Method	Targets	Notes
`addEventListener(type, fn, opts?)`	first-level DOM children	mirrors removeEventListener/dispatchEvent
`observeUsing(observer)`	first-level DOM children	IntersectionObserver or ResizeObserver; pair with `unobserveUsing`
`getClientRects()`	first-level DOM children	returns a flat `DOMRect[]`, one+ per child
`focus(opts?)` / `focusLast(opts?)`	all nested children, depth-first	finds the first/last focusable element
`blur()`	the active element, if inside the group	no-op otherwise
`scrollIntoView(alignToTop?)`	the group's children	boolean only — an options object throws
`getRootNode(opts?)` / `compareDocumentPosition(node)`	DOM tree queries	mirror the native `Node` methods

Must use <Fragment ref={...}> from import { Fragment } from "react" — not <>...</>.
A Fragment Ref never adds a DOM node. No node, no CSS hook — style the children themselves.
Requires react and react-dom 19.3.0 or later.

Key takeaways

A wrapper <div> added only to hold a ref is a real structural change — it becomes a layout participant whether you wanted one or not.
Fragment Refs (<Fragment ref={...}>, React 19.3+) give you a FragmentInstance with zero extra DOM, for group-level event listening, observing, focus, measuring, and scrolling.
Most methods — addEventListener, observeUsing, getClientRects — only see first-level DOM children; focus/focusLast search every nested child, depth-first.
scrollIntoView takes a boolean, not the options object the native DOM method accepts — passing one throws.
Reach for this when the group needs ref-powered behavior but not a visual wrapper; reach for a real element when it needs actual CSS.

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

That dashboard from the opening scene ships today with its IntersectionObserver intact and its six-column grid untouched — the fix was never the observer, it was the <div> standing in for a ref no element needed to carry. If you've shipped your own wrapper-for-a-ref before, the chances are decent a Fragment ref would have made it disappear entirely.

If rerender-vs-remount taught you that key controls which React instance you're looking at, this is the companion lesson on the other side of the same tree: a Fragment never had an instance of its own in the DOM, and now it can still hand you one anyway. And if you're already running React 19.3 for <ViewTransition>, Fragment Refs shipped in the very same release — it's worth knowing both landed together.

What's the ugliest wrapper-div-for-a-ref you've shipped — would a Fragment Ref have fixed it? 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___

You Added `will-change` to Fix the Jank. You Made It Worse.

Parsa Jiravand — Sat, 10 Oct 2026 12:11:59 +0000

Open DevTools on almost any site that's been "optimized" for animation and check the Layers panel. There's a decent chance half the card grid, the nav, a modal backdrop, and a few divs nobody can explain are each sitting in their own compositor layer — because at some point, someone added will-change: transform to fix a stutter, and it never came back off.

The property does exactly what it promises, which is the whole problem. Set it on one element, right before that element animates, and the browser can promote it to the GPU ahead of time instead of scrambling mid-animation. The jank goes away. That's a real, measurable win — and it's also the exact experience that teaches people the wrong lesson: will-change makes animations smooth, so sprinkle it wherever something moves.

That's the myth. It falls apart the moment it meets a loop.

The rule that's correct on one element and wrong on two hundred

Here's the version that ships after someone reads "just add will-change":

.card {
  will-change: transform;
}

If your page has one .card, this is fine — arguably exactly right. If .card is a grid of 200 dashboard tiles, this rule now applies to all 200 of them, permanently, the moment the stylesheet loads. Not "while hovering." Not "while animating." Forever, whether that card has moved once or never.

Each one of those 200 elements is a standing request to the browser: keep a compositor layer ready for this, indefinitely, just in case. MDN is direct about what that costs: "overusing the property can cause the page to slow down instead of improving its performance," and the fix is to use it "sparingly," on "deeply nested elements, containing as little of the document as possible" — the opposite of a blanket rule on a repeated class. The CSS spec puts the extreme case more bluntly: push it far enough and it "can cause the page to slow down or even crash."

There's also a version of this mistake the browser won't even let you make: will-change: all looks tempting as a catch-all, but it's explicitly disallowed in the spec, specifically so people can't do what the .card rule above does by accident with a long, honest property list instead.

Why the wrong lesson feels right

Nobody adds will-change to be reckless. They add it to one laggy modal, watch the animation go from choppy to smooth in DevTools, and reasonably conclude: more of this, applied more broadly, should help more. The demo that teaches the property is always a single element. The failure only shows up at scale, after the feature ships, on a machine with less GPU memory than whoever wrote the CSS was testing on — which is exactly the kind of bug report that never says "it's the will-change rule" in the subject line.

The mental model that actually holds up: a promise, not a setting

will-change isn't a performance mode you flip on. It's a promise to the browser, and like any promise, breaking it has a cost. "This specific element's transform is about to change" is a promise you can keep for one element for a few hundred milliseconds. "Every card in this grid might change at some unknown point" is a promise you can't keep, and the browser ends up paying for the ones you broke.

The pattern that holds up adds the hint in JavaScript, right before the change, and removes it right after:

const card = document.querySelector(".card");

card.addEventListener("pointerenter", () => {
  card.style.willChange = "transform";
});

card.addEventListener("transitionend", () => {
  card.style.willChange = "auto";
});

Now the browser only reserves a layer for the exact window where it's useful — from the moment you signal intent to the moment the transition actually finishes — and gives that memory back immediately after. One card hovered is one layer, briefly. Two hundred cards sitting untouched are two hundred cards costing nothing.

🎮 Try it yourself

▶️ Open the interactive playground →

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

When the old way — no `will-change` at all — is the right call

Most elements on most pages don't need this property, full stop. Browsers already run their own heuristics for promoting layers around transform and opacity changes, and for a single button or a handful of elements, those heuristics are usually good enough on their own. will-change is specifically for the case you've already profiled: you opened the Performance or Layers panel, watched a specific element genuinely struggle, and confirmed a manual hint fixes it. MDN's own framing is "use it as a last resort to deal with existing performance problems" — never "add it in advance in case one shows up." If you haven't profiled anything yet, you don't have evidence will-change is the fix; you have a hunch, and hunches are how a stylesheet ends up with a permanent rule on .card.

The honest caveat

will-change doesn't make anything faster in the way a code change makes a function faster — it changes when the browser pays a cost it was always going to pay, trading a little memory for a smoother first frame. On a memory-constrained device, that trade can go the other way: enough simultaneous layers and you're not avoiding jank, you're causing it, just somewhere else in the pipeline. The fix for "I added will-change and it's still janky" is often "remove will-change and check whether you're promoting too much at once" — not "add more of it."

The takeaway

will-change works exactly as advertised on exactly as much as you apply it to. The mistake was never the property — it was treating a scoped, temporary hint like a global setting you set once and forget. Scope it to the element that's actually changing, add it right before the change, take it back off right after, and you get the smooth animation without two hundred standing GPU layers paying for cards that never moved.

Go check your own stylesheet for a bare will-change sitting on a class that matches more than one element — how many of those elements have actually animated today?

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

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

📚 Read next

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

Thanks for reading! Let's stay connected:

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

You're Animating for Everyone. `prefers-reduced-motion` Fixes That.

Parsa Jiravand — Fri, 09 Oct 2026 06:10:28 +0000

Somewhere in your traffic right now is a visitor who went into their OS settings and turned on "Reduce motion." Maybe it's vestibular — a parallax hero genuinely makes them reach for the back button, sometimes mid-scroll, stomach first. Maybe it's just a preference. Either way, they told their computer. Your CSS never asked.

That's the part that's easy to miss: this isn't a setting you'd need to build. It already exists, it's already wired into every major OS, and the browser already knows the answer. There's a one-line CSS media feature that reads it. Almost no one uses it, and most of the people who do use it get the "safe" version backwards — in a way that doesn't look wrong in a code review.

The fix that breaks the loading spinner

Here's what usually happens the first time someone audits a site for motion sensitivity and feels bad about what they find. They add one rule at the top of the stylesheet and call it done:

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation: none !important;
    transition: none !important;
  }
}

Ship it, close the ticket, feel good. Then the bug reports start: the loading spinner doesn't spin anymore — it just sits there, frozen, looking broken instead of busy. The focus ring that used to ease in now snaps so hard it looks like a rendering glitch. The toast that confirms "Saved" pops in and out with no transition at all, so on a slow glance it looks like nothing happened.

Turns out !important doesn't know the difference between a parallax hero that exists purely to look cool and a spinner whose entire job is to show the page is still alive. It nuked both.

Decorative motion and motion that's doing a job

Here's the distinction the blanket rule missed, and it's the one thing to take from this whole post if you take nothing else: "reduce motion" does not mean "delete all motion."

The accessibility guidance behind this setting (it's closely related to WCAG's Animation from Interactions criterion, though that one specifically covers interaction-triggered motion) is about non-essential motion — parallax, auto-playing background video, swooping page transitions, anything whose only purpose is visual flair. Motion that's carrying information — a spinner proving a request is in flight, a focus ring proving where keyboard focus landed, a progress bar — should usually still move, just without the large transforms (scale, translate, 3D) that trigger a vestibular reaction. A spinner that still spins in place is fine. A spinner that slides across the screen while it spins is not.

So the real pattern isn't "delete everything inside the reduce query." It's "write the big, decorative motion so it only exists when the browser says no one asked for less of it":

.hero-card {
  opacity: 1;
  transform: none;
}

@media (prefers-reduced-motion: no-preference) {
  .hero-card {
    /* the swoop-in effect lives entirely inside this query */
    animation: swoop-in 600ms ease-out;
  }
}

.spinner {
  /* rotation only — no translate, no scale — so it's left alone */
  animation: spin 900ms linear infinite;
}

Notice which media feature that first block uses: no-preference, not reduce. That's not a stylistic choice — it's the detail that makes the whole thing fail closed.

Why `no-preference` is the one to reach for

Quick check before you scroll: which of these two is safer if a browser, for whatever reason, doesn't evaluate the media feature at all?

/* A: opt OUT of motion */
.hero-card { animation: swoop-in 600ms ease-out; }
@media (prefers-reduced-motion: reduce) {
  .hero-card { animation: none; }
}

/* B: opt IN to motion */
.hero-card { animation: none; }
@media (prefers-reduced-motion: no-preference) {
  .hero-card { animation: swoop-in 600ms ease-out; }
}

In version A, the animation is the default — it runs unless the reduce query actively matches. If the media feature can't be evaluated for any reason, nothing turns it off, and the visitor who asked for less motion gets the full swoop anyway. In version B, the animation is the thing that has to be earned — it only runs when the browser can positively confirm no-preference. If evaluation fails for any reason, the safe, motionless default is what's left standing.

prefers-reduced-motion itself has excellent support in evergreen browsers today, so this isn't about Internet Explorer. It's about not betting your accessibility behavior on an active override firing correctly, when you could just as easily make stillness the thing that happens by default and motion the thing you have to opt into.

The part CSS can't fix for you

Here's the open loop from the start of this post: the visitor whose stomach can't handle your parallax hero isn't only fighting your CSS. A lot of the motion that actually triggers a reaction never goes through a transition or animation property at all — it's a requestAnimationFrame loop moving a background layer on scroll, or a hero video with autoplay and no regard for anyone's settings. @media (prefers-reduced-motion: reduce) has zero effect on either, because neither one is CSS.

JavaScript gets the same preference through window.matchMedia() — the same API behind watching other media queries from JS — and, same as any other media query, you can subscribe to it changing live, without a page reload:

const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)");

function applyPreference(matches) {
  if (matches) {
    cancelAnimationFrame(parallaxLoop);
    heroVideo.pause();
    heroVideo.removeAttribute("autoplay");
  } else {
    parallaxLoop = requestAnimationFrame(runParallax);
  }
}

applyPreference(reduceMotion.matches);
reduceMotion.addEventListener("change", (e) => applyPreference(e.matches));

That change listener matters more than it looks: if someone flips "Reduce motion" on in their OS settings while your tab is already open — which is exactly what someone mid-vertigo is likely to do — the parallax loop stops without them needing to reload anything.

🎮 Try it yourself

▶️ Open the interactive playground →

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

The honest caveat

One thing this setting can't do: tell you about a visitor who has the exact same sensitivity but never found, or never bothered with, the OS toggle. prefers-reduced-motion: no-preference is what you get both from someone who genuinely loves motion and from someone who simply doesn't know the setting exists. Respecting the media query is necessary, not sufficient — if your product leans heavily on motion, an in-app "reduce animations" toggle that doesn't require touching OS settings is still worth having alongside it, not instead of it.

The takeaway

The setting was never the hard part — it's one media feature, supported everywhere that matters, and your OS has been asking the browser about it for years. The hard part is remembering that "respect it" means separate decorative motion from functional motion and default to still, not delete transitions wherever you find the word animation. Next time you reach for that one global override, flip it around: wrap the swoop in no-preference instead of silencing it in reduce.

Go check your hero section right now — does the parallax or the autoplaying background video even know this setting exists, or does it just keep moving no matter what the visitor asked for?

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

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

📚 Read next

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

Thanks for reading! Let's stay connected:

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

Stop Losing Promise Errors. `unhandledrejection` Catches Them.

Parsa Jiravand — Thu, 08 Oct 2026 06:10:23 +0000

Three weeks. That's how long it took anyone to notice that a subset of checkouts were quietly failing — not erroring, not crashing, just... not completing. No red line in the dashboard. No spike in the error tracker. Support tickets trickled in ("I clicked pay and nothing happened"), got marked as user error, and closed.

The bug was two lines of code: a fetch() call inside an async handler, with no .catch() anywhere on its chain. When the payment API returned a validation error, the promise rejected, the handler silently stopped executing, and the rejection went — nowhere. Not to the console in a way anyone was watching. Not to Sentry. Not to anyone.

The code that looks finished

This is the version almost everyone ships, because it looks complete:

button.addEventListener("click", async () => {
  button.disabled = true;
  const res = await fetch("/api/checkout", { method: "POST", body: cartPayload });
  const order = await res.json();
  showConfirmation(order);
});

It handles the happy path. It awaits both calls. There's no obvious hole. Run it against a working API and it's correct.

Now make fetch reject — a network drop, a CORS misconfiguration, or res.json() throwing because the server returned an HTML error page instead of JSON. The await re-throws inside the async function, the function's returned promise rejects, and since nothing ever attaches a .catch() to that promise — the event listener doesn't return it to anyone, it just fires it and walks away — the rejection has no handler. button.disabled stays true forever. The user sees a button that quietly stopped working. And unless you know to look, you'll never know it happened.

Why your error tracker didn't catch it

This is the part that surprises people: an unhandled promise rejection is not the same event as a runtime error, and plenty of error-monitoring setups only wire up the one they thought of first.

A thrown error outside a promise fires window.onerror (or the error event on window) — most basic error tracking hooks this.
A promise that rejects with nobody attached to catch it fires a different event: unhandledrejection. If you never listen for it, the only sign it happened is a console line — Uncaught (in promise) TypeError: ... — that nobody sees unless DevTools is already open and someone is looking at exactly the right tab.

Full error-tracking SDKs like Sentry do wire this up for you by default. A hand-rolled window.onerror = reportError does not. That gap is exactly where the checkout bug lived for three weeks.

The listener that closes the gap

The fix is one global listener, and it's been supported in every major browser for years:

window.addEventListener("unhandledrejection", (event) => {
  // event.reason is whatever the promise rejected with —
  // usually an Error, but not guaranteed (someone could `reject("oops")`)
  reportError(event.reason, { source: "unhandledrejection" });

  // optional: stop the "Uncaught (in promise) ..." console noise,
  // now that you've reported it somewhere that actually gets read
  event.preventDefault();
});

event here is a PromiseRejectionEvent, with two properties worth knowing: event.promise (the promise that rejected) and event.reason (the value it rejected with — often an Error, but JavaScript lets you reject with anything, so don't assume it has a .message). Calling event.preventDefault() suppresses the browser's own "Uncaught (in promise)" console message — worth doing once you're actually reporting the rejection somewhere, so you're not logging it twice.

There's a companion event, rejectionhandled, that fires if a .catch() shows up after the fact — say, a .then() chained in asynchronously once some other code finishes loading. It exists so you can retract a report you already sent for a rejection that turned out to be handled, just late. Most apps never need it; it's there if your reporting pipeline needs to avoid false positives on timing-sensitive code.

🎮 Try it yourself

▶️ Open the interactive playground →

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

The one thing it doesn't do

Be clear about what this buys you, because it's tempting to treat a global listener like a fix: it isn't one. unhandledrejection doesn't stop the checkout button from getting stuck, doesn't retry the request, and doesn't tell the user anything went wrong. All it does is make a failure that was previously invisible show up somewhere you'll actually read it. The underlying bug — a .catch() or a try/catch that should have been there — still needs fixing at the source. What the listener changes is how long that bug survives before someone notices.

It's also browser-only as written above: in Node.js, the equivalent is process.on("unhandledRejection", (reason, promise) => { ... }), and every Node release since v15 (2020) goes further than a warning — by default, an unhandled rejection now terminates the process instead of just logging it, which is its own argument for not leaving async error handling to chance.

What this is really for

Treat unhandledrejection the way you'd treat a smoke detector: it doesn't put out the fire, it just guarantees you find out about it before the room fills with smoke. Wire it into whatever already collects your errors — Sentry, a logging endpoint, even just a styled console group in staging — and the next silent failure stops being silent. The checkout bug above wasn't hard to fix once someone saw it. The three weeks were the cost of nobody seeing it.

Go check right now: does your app have a global unhandledrejection listener, or does it only catch the errors you remembered to wrap in try/catch?

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

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

📚 Read next

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

Thanks for reading! Let's stay connected:

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

Junior interviews don't test what they used to, and nobody updated you

Parsa Jiravand — Wed, 07 Oct 2026 06:10:50 +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.

You're in a loop for a role with "junior" or "entry-level" somewhere in the title, and the interviewer just asked you to walk through how you'd design something, then pushed back on your first answer, then asked what would make you change your mind. You came in ready to explain a for-loop and got cross-examined like you're six years into this. You leave thinking you bombed it, or that you're underqualified for a job that was supposed to be the easy one.

You didn't bomb it. The job changed underneath the title, and nobody sent out a memo.

What the junior job actually used to be

For a long time, "junior engineer" meant a specific, boring, valuable thing: you wrote the CRUD endpoint, you scaffolded the test file, you fixed the bug where the date was off by one, you wrote the first draft of the documentation nobody else wanted to write. It wasn't glamorous. It was also real work that needed doing, and doing it badly for a year or two was how you learned to do it well — with someone more senior checking your output line by line, which was its own kind of training you didn't even notice was training.

Here's the uncomfortable part: that specific list of tasks is almost exactly what AI tooling now does fastest and cheapest. Boilerplate, scaffolding, first-pass tests, routine fixes, a documentation draft — a senior engineer with a model open in another tab can produce all of that themselves, in less time than it takes to explain it to a new hire. So the tasks that used to justify a junior headcount got absorbed upward, into the senior engineer's own workflow. What's left, the part that didn't get absorbed, is judgment — noticing when the obvious approach is wrong, knowing when to stop and ask, catching your own mistake before it ships. That was never really the "junior" part of the job. It was the part you were supposed to grow into over a few years, with somebody checking your work the whole time.

That's the piece that broke. Companies still post junior roles. Some of them still mean it. But a lot of the loops are quietly testing for the leftover part — judgment — because that's the only part of the old job description that's still worth a human doing it. Nobody rewrote the posting to say that, because nobody's entirely sure how to word it yet. So you walk in prepared for the old test and get asked the new one.

So what are they actually listening for?

Not the right answer. They're listening for whether you can catch yourself.

When they ask you to walk through an approach, don't just state the answer — narrate the decision. "Here's what I'd try first, and here's the thing that would make me stop and try something else instead." That one sentence does more work than a correct solution delivered with no visible thinking, because it shows you have a way of checking your own output. That's the skill that used to get built by someone else checking it for you. Showing you already do some of that yourself is the whole signal.

When you genuinely don't know something — and in a junior loop you will hit one of these — say it plainly and show the next step: "I don't know that off the top of my head. I'd start by checking X, and if that didn't explain it I'd go look at Y." That's not a weaker answer than a guess. A confident wrong guess is the single worst thing you can do in this kind of loop right now, because it reads as exactly the failure mode they're trying to screen out: someone who needs a person standing over them to catch the thing they didn't know they didn't know.

And when they ask about a time something went wrong — even a small, practice-project, nothing-at-stake kind of wrong — give them the moment you noticed, not just the fix. "I noticed the numbers looked off before I'd even run the test, because they were too round" tells them something a fixed bug alone doesn't: that you were paying attention to your own work, not just producing it and moving on.

Some loops now ask the blunt version directly: why bring on someone junior at all, when the senior engineers already have the tooling to move fast on their own? Don't argue with the premise — it's half true. The honest answer is closer to: "Because someone still has to be the person who eventually doesn't need the tooling checked, and that only happens by doing the work now, badly at first, with someone watching." You're not claiming to be faster than the alternative. You're naming the thing you're actually there to become, which is a different pitch than the one the posting was written for a few years ago.

Where this backfires

Push this too far and you walk in performing total self-sufficiency — no hesitation, no "I'd want a second opinion on this," every answer delivered like you've never needed help. That's not what judgment looks like either. Judgment includes knowing the edge of what you know, and an interviewer who's actually any good can tell the difference between someone who's thought it through and someone who's just not admitting to any gaps. The honest "here's where I'd want someone more experienced to sanity-check me" is not a weaker answer. For a role with "junior" in the title, it's often the correct one — it shows you know the limit exists, which is most of the judgment they're testing for in the first place.

The part that isn't fair, and I'll say it plainly

If you are genuinely new to this — no internship, no bootcamp project that shipped to real users, nothing — this bar is not fair to you yet, and pretending otherwise would be a lie dressed up as encouragement. Judgment about when to double-check your own work is something people build through reps, and if the industry quietly moved the goalposts on how many reps you're owed before you're expected to have it, that's not a gap in you. It's a gap in how the pipeline was supposed to work. You can still show up and demonstrate the small amount of judgment you do have — plenty of people have some, built from school, from side projects, from just paying close attention — but if you don't get the offer, it is worth knowing the test itself shifted, and not every company re-leveled their expectations to match. Some of what happens next is you finding the ones that did. And some of it, like most hiring, is luck and timing you don't control — who else applied that week, whether the team had budget that quarter, whether the interviewer had a good morning. Naming that doesn't mean the preparation doesn't matter. It means the preparation isn't the whole story, and you shouldn't carry the parts that aren't yours to carry.

Monday

Before your next interview, pick one technical decision from something you've actually built — a side project, a class assignment, anything — and practice saying it out loud, start to finish, including the part where you'd check yourself: what you'd try first, and the specific thing that would make you stop and reconsider. Say it to your phone, play it back. You're not rehearsing the answer. You're rehearsing the sentence that shows you'd catch your own mistake, because that's the sentence the room is actually listening for now.

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

Thanks for reading! Let's stay connected:

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

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

Stop Retrying Immediately. Exponential Backoff Fixes It.

Parsa Jiravand — Wed, 07 Oct 2026 06:10:20 +0000

The API call fails. Your retry logic kicks in — of course it does, you wrote it for exactly this. Five attempts, back to back, as fast as the event loop allows. The first one failed in 40ms. By 200ms you've fired all five.

That's the whole bug. Not that you retried — that you retried immediately, which is the one thing a failing server can least afford.

The retry loop that feels obviously right

Here's the version almost everyone writes first:

async function fetchWithRetry(url, retries = 5) {
  for (let i = 0; i < retries; i++) {
    try {
      const res = await fetch(url);
      if (res.ok) return res;
    } catch {
      // network error — fall through and try again
    }
  }
  throw new Error(`Failed after ${retries} attempts: ${url}`);
}

It reads like good engineering. A flaky request gets a second chance, then a third, up to five, before you give up and surface an error. Test it against a healthy endpoint that you fail on purpose for one call, and it works perfectly — the second attempt succeeds, nobody notices.

The test that never runs is the one where the server is the problem. A deploy goes out with a bad config, a dependency times out, a traffic spike pushes response times past your fetch timeout. Now every client hitting that endpoint gets a failure — and every client's retry loop fires its five attempts in the same few hundred milliseconds. The server that was struggling under normal load now gets 5x the request volume, instantly, from every caller that was already in flight. That's not recovery. That's a second, self-inflicted spike landing directly on top of the first one.

This has a name — a retry storm — and it's a well-documented failure mode in distributed systems, not a hypothetical. The fix isn't "retry less." It's "retry differently."

What the loop is actually missing

Three things, and none of them are exotic:

A growing delay between attempts, so a struggling server gets breathing room instead of an immediate second hit.
Randomness in that delay, so thousands of clients that all failed at the same moment don't all retry at the same moment too.
A reason not to retry everything — a 404 will fail the same way on attempt five as attempt one. Retrying it five times doesn't help; it just makes you look five times slower at reporting the real error.

Put those together and you get exponential backoff with jitter: each retry waits roughly twice as long as the last, capped at some maximum, and the exact wait is randomized within that window instead of fixed.

async function fetchWithRetry(url, { retries = 4, baseDelay = 300, maxDelay = 8000 } = {}) {
  for (let attempt = 0; ; attempt++) {
    let res;
    try {
      res = await fetch(url, { signal: AbortSignal.timeout(5000) });
    } catch (err) {
      if (attempt === retries) throw err;
      await backoff(attempt, baseDelay, maxDelay);
      continue;
    }

    if (res.ok) return res;
    if (res.status < 500 && res.status !== 429) return res; // a client error won't fix itself
    if (attempt === retries) return res;

    await backoff(attempt, baseDelay, maxDelay, res.headers.get("Retry-After"));
  }
}

function backoff(attempt, base, cap, retryAfter) {
  if (retryAfter) {
    const seconds = Number(retryAfter);
    const ms = Number.isFinite(seconds) ? seconds * 1000 : new Date(retryAfter).getTime() - Date.now();
    return sleep(Math.max(0, ms));
  }
  const windowMs = Math.min(cap, base * 2 ** attempt);
  return sleep(Math.random() * windowMs); // "full jitter" — pick anywhere in the window, not the edge
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

Walk through what changed, because each line is answering one of the three gaps above:

AbortSignal.timeout(5000) caps how long a single attempt can hang before it counts as a failure and moves on to the backoff — without this, one slow attempt can eat your whole retry budget just sitting in fetch's pending state.
res.status < 500 && res.status !== 429 stops the loop from wasting attempts on a 400 or 404 — those are the server telling you the request itself is wrong, and no amount of waiting changes that. 429 (rate limited) and 5xx (server trouble) are the ones worth retrying.
Retry-After is a real HTTP response header — servers send it on 429 and 503 to tell clients how long to wait before trying again (it also shows up on some 3xx redirects, for a different reason) — as a number of seconds, or an HTTP date. When it's there, use it instead of guessing; the server is telling you its own recovery estimate.
Math.random() * windowMs is "full jitter": instead of every client waiting exactly 300ms, then exactly 600ms, then exactly 1200ms — which just re-synchronizes everyone's retries into new, smaller storms — each client picks a random point inside that window. Spread the same total number of retries over time instead of in lockstep, and the server sees a trickle instead of a wave.

🎮 Try it yourself

▶️ Open the interactive playground →

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

The attempt nobody should auto-retry

One more thing the naive loop glossed over: it retried everything, including requests that aren't safe to repeat. A GET is idempotent — running it five times has the same effect as running it once. A POST that creates an order is not. If that request actually reached the server and created the order, but the response got lost on the way back, retrying blindly creates a second order.

The honest fix is smaller in scope than it sounds: only wrap genuinely idempotent requests (GET, HEAD, a PUT that fully replaces a resource) in automatic retry by default. For a POST you need retried — payment confirmation, for instance — the real fix is an idempotency key: a unique ID you generate once and send with every attempt, so the server can recognize "I've already done this one" and return the original result instead of doing it twice. That's a server-side contract, not something fetchWithRetry can fake on its own — which is exactly why it's worth calling out instead of quietly auto-retrying a POST and hoping.

What this actually buys you

None of this makes requests succeed that were always going to fail — a backoff loop retrying against a server that's down for an hour will still, eventually, give up. What it changes is the shape of the load your retries put back on a server that's recovering: spread out instead of synchronized, bounded instead of infinite, and aimed only at the failures that stand a chance of succeeding on a second try.

The three-line fix really is three lines — a growing delay, a random window inside it, and a check for which status codes deserve a second attempt. Getting there meant admitting the first version wasn't "retrying too little" or "retrying too much." It was retrying at exactly the wrong tempo.

What's your current retry count, and have you ever actually watched what it does to a server that's already struggling?

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

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

📚 Read next

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

Thanks for reading! Let's stay connected:

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

I Built Cross-Tab Logout. The storage Event Skipped One Tab.

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

Three tabs open, same account, same session. Click "log out" in the middle one, and the plan is simple: every tab reacts, every tab redirects to the login screen, nobody's left holding a stale session.

I wired it the way you'd expect — localStorage.setItem('session', JSON.stringify({ loggedIn: false })) on logout, a window.addEventListener('storage', ...) listener that reads the new value and updates the UI. Opened two tabs to test it. Clicked logout in the first.

The second tab redirected instantly. The first tab — the one I'd just clicked in — sat there, fully rendered, still logged in, still showing the account menu, like nothing had happened.

The obvious read: "listen for storage changes"

Before BroadcastChannel existed (and still, in plenty of production code, when you need something that works back to IE11 and doesn't need a build step), the storage event was the way to sync tabs. The pitch is simple: any tab writes to localStorage, every other tab watching that origin gets notified.

function applyLogout(loggedIn) {
  if (!loggedIn) {
    renderLoggedOut();
  }
}

window.addEventListener("storage", (e) => {
  if (e.key !== "session") return;
  const { loggedIn } = JSON.parse(e.newValue);
  applyLogout(loggedIn);
});

// somewhere in the logout button's click handler:
localStorage.setItem("session", JSON.stringify({ loggedIn: false }));

Reasonable code. It even looks correct in a two-tab test, if you only check the other tab. I didn't — I assumed the tab making the change would see its own write reflected the same way, because that's how almost every other kind of state-change notification behaves: you change something, your own UI picks it up.

What's actually happening: the event skips its origin

It's in the first sentence of MDN's page for the event, which I'd clearly skimmed instead of read: the storage event fires on Window objects other than the one that made the change. The tab that calls setItem doesn't get a storage event for its own write — not sometimes, not as a quirk in one browser. Every engine implements it this way, because the event's whole job is telling other documents "something changed somewhere else." The document where it changed already knows; dispatching the event back to itself would just be an echo.

Two more edges worth knowing while you're down here, because they're exactly the kind of thing that passes a two-browser-tab smoke test and then breaks in a slightly different shape in production:

No real change, no event. setItem('theme', 'dark') when theme was already 'dark' doesn't fire anything, anywhere — the spec compares old and new values first. If your UI update logic lives entirely inside the storage listener, writing the "same" value on purpose (to force a refresh, say) silently does nothing.
clear() reports key: null. Wiping the whole storage area doesn't name a key — event.key, oldValue, and newValue all come back null, which is the spec's way of saying "everything," not "nothing."

Neither one bit me this time. The missing self-notification did, because the entire feature's correctness depended on exactly one tab — the one where the user clicked — getting word of its own action, and that's precisely the tab the event is defined to skip.

The fix is two call sites, not a different API

The temptation is to blame the event and reach for something else. The actual fix is smaller: stop treating "write to storage" and "update this tab's UI" as the same step just because they usually travel together.

function applyLogout(loggedIn) {
  if (!loggedIn) {
    renderLoggedOut();
  }
}

window.addEventListener("storage", (e) => {
  if (e.key !== "session") return;
  const { loggedIn } = JSON.parse(e.newValue);
  applyLogout(loggedIn); // every OTHER tab arrives here
});

function logout() {
  localStorage.setItem("session", JSON.stringify({ loggedIn: false }));
  applyLogout(false); // THIS tab has to call itself — no event is coming
}

One function, two call sites: the listener covers every tab that didn't make the change, and the action itself covers the one that did. It's an easy rule to forget specifically because it's invisible in testing unless you remember to check the tab you clicked in — which, if you're the one testing your own feature, is also the tab you're already looking at and already know the "right" answer for.

The one thing this old API still does that a newer one can't

It's tempting to read all of this as "just use BroadcastChannel instead" — the API that replaced storage-event tab-syncing for most new code, because it skips the JSON-stringify dance and doesn't fire on unrelated key changes. It's a genuinely better fit for most of what people reach for storage events to do.

But it trades away something the storage event gets for free, because localStorage isn't just a message pipe — it's a place the value actually lives. Open a third tab a few minutes after the logout happened in the other two, with no tabs sending anything at that moment, and it still loads logged out — because on load, it reads localStorage.getItem('session') directly, the same way it would read any other persisted value. There was no message to miss, because nothing had to be delivered. BroadcastChannel only reaches tabs that are listening at the moment a message is posted; a tab that opens later never receives what it missed, because there's nothing left to receive — the channel doesn't keep a backlog. If a new tab needs to know the current state rather than just future changes to it, something has to persist that state somewhere readable — and localStorage plus the storage event is still a reasonable way to get both the persistence and the live update in one write.

🎮 Try it yourself

▶️ Open the interactive playground →

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

Try it with two real tabs

Everything above is easy to nod along to and easy to get backwards in actual code, because the bug only shows up in the tab you're not looking at — or, worse, the one you are, silently not updating while you assume it did. Open the demo below in two tabs and watch both directions at once: the tab that writes, and the tab that's told.

The part worth remembering

None of this is a storage-event bug. It's a one-line spec detail that's easy to miss because almost nothing else behaves this way — you change a variable, your own scope sees the new value; you call a setter, your own component re-renders. A browser event that deliberately excludes the one document that caused it is the exception, not the rule, and the only way to catch it before production is to actually check the tab you clicked in, not just the one next to it.

What's the last cross-tab or cross-window feature you shipped where you only tested the other window?

🧠 Test yourself

Think it clicked? Take the 8-question quiz →

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

📚 Read next

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

Thanks for reading! Let's stay connected:

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

Next.js Streaming Metadata: Why Your `` Looks Incomplete

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

You add a generateMetadata function to a product page so the <title> and Open Graph image come from your CMS instead of a hardcoded string:

// app/products/[slug]/page.tsx
export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const product = await getProductFromCMS(slug); // ~2s on a slow day
  return {
    title: product.name,
    openGraph: { images: [product.heroImage] },
  };
}

It works. You click the link in Chrome, the tab title updates, the page looks exactly right. You ship it.

Two days later, someone pastes the link in Slack and the unfurled card shows your site's generic fallback title and no image — as if generateMetadata never ran. You paste the same URL into curl to debug it, and the very first chunk of HTML that comes back really does have the fallback <title>, not the product name. Your function isn't broken. You've just met streaming metadata — a real behavior difference between how Next.js answers a browser and how it answers everything else, and it has been the stable default since Next.js 15.2.

What you'll learn

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

Explain why a slow generateMetadata can look instant in a browser tab but still show stale tags to a link-preview bot or a bare curl
Describe exactly which bytes Next.js sends first, and when the real <title> and Open Graph tags actually land
Use htmlLimitedBots to decide, on purpose, which clients get the blocking contract instead of the streaming one
Extend parent metadata with await parent instead of refetching data a layout above you already resolved
Avoid the one mistake that turns this feature into a real production liability: slow work inside generateMetadata, which still blocks every bot on your list

Who this is for

You've shipped at least one generateMetadata function — a dynamic <title>, an Open Graph image, something that depends on route params or a fetch. You don't need prior exposure to streaming or Suspense; this article builds the model from the response bytes up.

This is written against Next.js 16.3 (verified via npm's latest dist-tag, currently 16.3.8, and the framework's own documentation, October 2026). Streaming metadata shipped as experimental in Next.js 15 and has been stable since 15.2; nothing about the behavior described here is new to 16, but it's still the single most common surprise in generateMetadata issues on GitHub, and 16's default htmlLimitedBots list is the one you'll actually be configuring today.

The problem: one fetch, two different first impressions
The mental model: two contracts, one function
Stage 1: what a streaming client actually receives
Stage 2: what a blocked client actually receives
Stage 3: deciding who gets blocked, with htmlLimitedBots
Stage 4: extending metadata instead of refetching it
Stage 5: when there's nothing to stream at all
Edge cases and gotchas
Best practices
FAQ
Cheat sheet

The problem: one fetch, two different first impressions

Before streaming metadata existed, the rule was simple and expensive: Next.js would not send any HTML until generateMetadata fully resolved. A 2-second CMS call meant a 2-second blank screen for every visitor, every time, because the framework had no way to show a page without first knowing what goes in its <head>.

Next.js 15.2 changed the contract for ordinary visitors. Now, for a dynamically rendered route, the initial HTML can stream to the browser before generateMetadata resolves — using placeholder or previously-resolved values where needed — and the real tags arrive moments later, once the promise settles. A human never waits on your CMS call to see the page.

But a <title> that arrives after the first paint is invisible to anything that doesn't execute JavaScript and re-read the DOM: a link-unfurling bot, an RSS reader, a quick curl, most SEO crawlers. For those clients, "the tags arrive eventually" isn't good enough — they read once and move on. So Next.js detects them by User-Agent against a built-in (and configurable) list called htmlLimitedBots, and for anyone on that list it reverts to the old, blocking contract: wait for generateMetadata, then send one complete document.

That's the whole story behind the Slack bug above. Slack's unfurler matched the bot list and got the honest, complete, slow response. Your own curl test — run without a recognizable bot User-Agent — got the fast, streaming response, and happened to catch it before the real tags landed. Nothing was broken; two different clients were served two different, equally-intentional contracts.

The mental model: two contracts, one function

The mental model: generateMetadata always runs the same way — same code, same params, same parent metadata — but Next.js wraps its result differently depending on who's asking:

A regular client (browsers, most tools) gets the streaming contract. The initial HTML ships immediately with whatever metadata is already known — static values from export const metadata, and anything resolved by parent segments — plus a placeholder for what's still pending. When generateMetadata resolves, Next.js streams the real tags down the same connection and appends them to the end of the document — the same out-of-order delivery trick React already uses to fill in a <Suspense> boundary's content after the fact. Because <title>, <meta>, and <link> are tags React treats as hoistable, the browser moves them into the document's actual <head> the moment they arrive, so the live DOM ends up looking correct even though the bytes landed after <body>.
A client matched against htmlLimitedBots gets the blocking contract. Next.js withholds the response until generateMetadata (and anything it awaits) finishes, then sends one document with a complete, final <head> from the first byte. This is deliberately the old behavior, kept alive on purpose for exactly the clients that need it.

Neither contract is a bug version of the other — they're both correct, for different audiences. The mistake is assuming there's only one.

Stage 1: what a streaming client actually receives

Take a route with a 2-second metadata fetch and open it in a real browser with the network panel recording document load. You'll see the initial HTML response arrive almost instantly, containing:

<head>
  <!-- whatever resolved synchronously or came from a parent layout -->
  <meta charset="utf-8" />
  <!-- nothing reserved here for the pending tags — they arrive later, appended after <body> -->
</head>
<body><!-- your page's visible content, already rendering --></body>

A moment later — once getProductFromCMS resolves — Next.js streams the real <title> and openGraph tags over the same connection and appends them near the end of <body>. Because those are tags React hoists automatically, the browser relocates them into the document's real <head> as soon as they arrive. View the rendered DOM in DevTools after the page settles and it looks completely normal: a full, correct <head>. View the raw network response (or a tool that reads bytes instead of executing scripts) and the tags you expected simply aren't there yet — and when they do arrive, they show up appended after the body content, not spliced into the original <head> block.

Key concept: streaming metadata doesn't make generateMetadata run faster — it makes the page stop waiting for it. The fetch still takes 2 seconds; what changes is who's forced to sit through them.

Stage 2: what a blocked client actually receives

Now fetch the same URL with a User-Agent on the default bot list — Slackbot, Twitterbot, facebookexternalhit, and Bingbot are the kind of names it covers out of the box, along with Google's non-rendering crawlers like AdsBot-Google and Mediapartners-Google (the mainline Googlebot executes JavaScript and reads the full DOM, so Next.js explicitly verifies it gets a correct result from the streaming contract instead — it isn't one of the blocked clients):

curl -A "Slackbot" https://example.com/products/wireless-mouse

This request hangs for roughly 2 seconds — the full CMS fetch — and then returns one complete HTML document with the real product title and Open Graph image already in <head>. There is no placeholder, no follow-up script: this client only ever sees the finished page.

Key concept: the blocking contract isn't a fallback or a degraded mode — it's the one guarantee these clients actually need. A link-preview bot that reads one response and never runs JavaScript would never see a streamed-in tag; blocking is the only way to get it a correct result at all.

Stage 3: deciding who gets blocked, with `htmlLimitedBots`

The default list covers the obvious cases — major search crawlers and the social platforms' unfurlers — but it can't know about an internal tool, a less common regional crawler, or your own link-preview microservice. Configure it explicitly in next.config.ts:

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

const nextConfig: NextConfig = {
  htmlLimitedBots: /Slackbot|Twitterbot|facebookexternalhit|MyInternalLinkBot/i,
};

export default nextConfig;

Setting htmlLimitedBots replaces the built-in list rather than extending it, so if you only want to add one bot to Next's defaults, you need to also include the ones you still want covered. Treat it as "here is my complete list," not "here is one more entry."

Key concept: this isn't a performance knob — it's a correctness decision about who gets the blocking guarantee. Add a client here only if it genuinely can't handle a streamed-in tag; adding more than necessary just reintroduces the slow blank-page problem you got streaming to avoid.

Stage 4: extending metadata instead of refetching it

generateMetadata's second argument, parent, is a promise of everything already resolved by segments above the current one in the tree. Reach for it instead of re-fetching data a layout already fetched:

// app/products/[slug]/page.tsx
import type { ResolvingMetadata } from 'next';

export async function generateMetadata(
  { params }: { params: Promise<{ slug: string }> },
  parent: ResolvingMetadata,
) {
  const { slug } = await params;
  const product = await getProductFromCMS(slug);
  const previousImages = (await parent).openGraph?.images ?? [];

  return {
    title: product.name,
    openGraph: {
      images: [product.heroImage, ...previousImages],
    },
  };
}

Awaiting parent doesn't trigger a second network call — it resolves to the same metadata object the parent layout's own generateMetadata already produced, merged according to Next's normal child-overrides-parent rules.

Key concept: parent composes metadata down the tree the same way props compose components. A layout that fetches an organization's default share image once shouldn't make every page beneath it fetch it again just to append to it.

🎮 Try it yourself

▶️ Open the interactive playground →

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

Stage 5: when there's nothing to stream at all

Streaming only matters for a dynamically rendered route with a generateMetadata that depends on something not known at build time. If a route is statically rendered — no runtime params, every fetch inside generateMetadata cacheable — the entire <head> resolves once, at build time, and ships as part of the single prerendered document for every visitor and every bot alike. There's no placeholder and no follow-up script, because there's nothing left pending by the time anyone requests the page.

This is the same static/dynamic split the series covered from the application-caching side in Next.js Cache Components Explained — a route whose data layer is fully cached or static also gets a fully resolved <head> for free, with nothing to stream. Streaming metadata only earns its keep on the routes that are genuinely dynamic, which is also where Route Handlers' caching defaults matter most. Neither article is required to follow this one, but the two caching models rhyme.

Edge cases and gotchas

A slow generateMetadata still fully blocks every client on your htmlLimitedBots list. Streaming protects browsers, not bots. If your CMS call regresses from 200ms to 4 seconds, every listed crawler waits the full 4 seconds. Cache that fetch the same way you'd cache any other request-blocking data source.
generateMetadata that itself reads cookies() or headers() becomes request-specific, forcing the route dynamic (or requiring its own <Suspense> placement under Cache Components) regardless of streaming metadata — the two behaviors are independent, and you can hit both at once.
A client not on the bot list but that also doesn't execute JavaScript — a naive scraper, an old integration — sees whatever was in the initial response the moment it read it, which may be the placeholder. Add it to htmlLimitedBots if you control it, or have it execute JS like a browser would.
"View page source" in some browsers shows the pre-hydration snapshot, not the live DOM — it can look like the bot-blocked bug even when the browser itself renders the final tags correctly. Verify with DevTools' Elements panel or a real unfurl test, not raw view-source.

Best practices

Cache the data generateMetadata depends on. It's on the hot path for every blocked bot, so treat its latency as a production SLA, not an afterthought.
Keep the default htmlLimitedBots list unless you have a specific reason to change it. It already covers the clients most teams care about; a narrower custom list is easy to under-specify.
Test real unfurl surfaces, not just curl with a guessed User-Agent — Slack, Discord, and X's own debugging tools will show you the response their actual crawler gets.
Extend parent instead of refetching anything a layout above the current segment already resolved.
Don't read runtime APIs inside generateMetadata unless the metadata genuinely is per-request — it couples this function's cost to the same dynamic-rendering rules as the rest of the route.

FAQ

Why does my page look correct in Chrome but show the wrong title when shared in Slack?

Chrome is a streaming client — it renders the placeholder first, then updates to the real tags once generateMetadata resolves, within the same page load, so you never notice two states. Slack's unfurler is on the htmlLimitedBots list and should get the fully-resolved document; if it's showing stale data instead, the usual cause is the unfurler caching its own previous fetch of your URL, not a Next.js bug. Force a fresh unfurl with your platform's cache-busting tool before assuming the response is wrong.

Can I turn off streaming metadata entirely?

Yes, by setting htmlLimitedBots to a pattern that matches everyone (/.*/), though that reintroduces the original cost: every visitor waits for generateMetadata before seeing anything. It's rarely the right trade — add specific clients to the list instead of blocking universally.

Is streaming metadata the same thing as Partial Prerendering or Cache Components?

Related, not identical. Cache Components and Partial Prerendering govern which parts of the page body are static, cached, or streamed. Streaming metadata is the same idea applied specifically to the document <head>, and it ships independently — you get it on a dynamic route whether or not you've opted into cacheComponents.

Does `generateMetadata` run before or after my page component?

Next.js runs generateMetadata and your page's rendering work in parallel where possible, not strictly sequentially — the streaming behavior exists precisely so the page's visible content doesn't have to wait in line behind the metadata fetch.

Does this affect static routes at all?

No. A fully static route resolves its entire <head> at build time, so every visitor — human or bot — gets the same single, complete document. Streaming only has something to do on a dynamically rendered route.

Cheat sheet

Situation	What happens	Configure with
Regular browser, dynamic route	Initial HTML streams immediately; real tags arrive once `generateMetadata` resolves	Default behavior since Next.js 15.2
Client matched by `htmlLimitedBots`, dynamic route	Response blocks until `generateMetadata` resolves; one complete document sent	`htmlLimitedBots` in `next.config.ts`
Any client, static route	`<head>` resolved once at build time; nothing to stream	N/A — determined by static/dynamic rendering
Extending a parent's metadata	`await parent` inside `generateMetadata`, merge rather than refetch	`parent: ResolvingMetadata` second argument
`generateMetadata` reads `cookies()`/`headers()`	Becomes request-specific; subject to the same dynamic-rendering rules as the rest of the route	N/A — same rules as any runtime API read

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

Key takeaways

Next.js answers a browser and a bot differently on purpose: browsers stream past a slow generateMetadata, while clients matched by htmlLimitedBots wait for a complete, final <head>.
A bug report that only reproduces in a link-preview tool or curl, never in a real browser, is the signature of this exact feature — check which contract the failing client actually got before assuming the metadata is broken.
The blocking contract means generateMetadata's latency is still a real cost for every bot on your list — streaming hides it from humans, it doesn't delete it.
await parent composes metadata down the route tree without a second fetch; reach for it before duplicating a parent layout's data call.
None of this applies to a fully static route — streaming only has a job where the page is genuinely dynamic.

That Slack unfurl showing the fallback title from the opening story turned out to have nothing to do with your code at all — Slack's own cache had the old response, and re-sharing the link after busting it pulled the real, complete <head> your generateMetadata had been producing the whole time. The fix wasn't in generateMetadata. It was knowing which of the two contracts you were even looking at.

📚 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 defineModel: The v-model Contract, Explained

Parsa Jiravand — Mon, 05 Oct 2026 06:11:01 +0000

You've written this a dozen times: declare a modelValue prop, declare an update:modelValue emit, wire a computed's get/set between them, and hope you spelled the event name identically in both places. Misspell it — updata:modelValue, update:modelvalue, anything — and nothing errors; at most a dev-mode warning scrolls past. The parent's v-model just stops updating, and you're left bisecting a component that looks correct. Vue 3.4 replaced that whole dance with a single macro, defineModel. But it isn't new magic bolted onto v-model — it's Vue writing the same prop-and-event contract for you, and once you can see that contract, every edge case here becomes predictable instead of surprising.

What You'll Learn

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

Explain exactly what v-model on a component compiles down to
Replace the manual prop/emit/computed pattern with defineModel correctly
Give a model a default value, make it required, and type it in TypeScript
Bind multiple independent named models on one component
Read the modifiers a parent attaches to v-model and transform values with get/set

Who This Is For

You've built Vue 3 components with <script setup>, used defineProps and defineEmits, and put v-model on a native <input> at least once. This article is about what happens when you put v-model on your own component. If the read/write tracking underneath ref and reactive is still fuzzy, Vue Reactivity: ref vs reactive builds that foundation — useful background, not required reading.

The Problem: The Prop/Emit Dance, By Hand
The Mental Model: v-model Is Always a Prop and an Event
Building It Up: How defineModel Actually Works
Edge Cases and Gotchas
Best Practices
FAQ
Cheat Sheet
Key Takeaways

This is written against Vue 3.5.x (verified 3.5.43, released September 2026). defineModel has been stable, no-flag-required syntax since Vue 3.4 — nothing here needs the experimental flag that 3.3 required, and none of it changes in the 3.6 release candidate currently in testing: the only defineModel/useModel-related fix in 3.6 so far is a Vapor-mode-only regression fix, and this article doesn't use Vapor mode.

The Problem: The Prop/Emit Dance, By Hand

Say you're building a CurrencyInput component that a parent binds with v-model. Before defineModel, the idiomatic way to do this was a computed with a get and a set:

<!-- CurrencyInput.vue — the way you had to write it before Vue 3.4 -->
<script setup>
import { computed } from 'vue'

const props = defineProps({
  modelValue: { type: Number, default: 0 },
})
const emit = defineEmits(['update:modelValue'])

// A prop can't be written to directly — Vue warns and the write is dropped.
// So you build a local, writable stand-in with a get/set computed.
const model = computed({
  get: () => props.modelValue,
  set: (value) => emit('update:modelValue', value),
})
</script>

<template>
  <input
    type="number"
    :value="model"
    @input="model = Number($event.target.value)"
  />
</template>

This works, and it isn't wrong — but look at what it costs. The prop name (modelValue) and the event name (update:modelValue) have to match a convention exactly, in two separate declarations, with no compiler check tying them together. Get the emit name wrong in both places and v-model on the parent's side just does nothing: no warning, no error, no update (wrong in only one place, dev mode at least warns). Multiply this by every component with a two-way binding, and by every component that needs more than one — a firstName/lastName pair, say — and you're hand-writing the same four-line skeleton over and over, each copy a fresh chance to typo an event name.

defineModel collapses that entire block into one line:

<script setup>
const model = defineModel({ default: 0 })
</script>

<template>
  <input type="number" v-model.number="model" />
</template>

That's not a different feature — it's the same prop, the same event, and the same get/set relationship, generated for you from a single declaration.

The Mental Model: v-model Is Always a Prop and an Event

The mental model: whatever syntax you write on the outside, v-model on a component always compiles to exactly two things — a prop bound to the current value, and a listener for an event that writes a new value back up. v-model="x" on <MyInput> is shorthand for :model-value="x" @update:model-value="x = $event". That's the entire contract. Every version of "two-way binding on a component" Vue has ever shipped — the value/input convention in Vue 2, the modelValue/update:modelValue convention in early Vue 3, and defineModel today — is just a different amount of automation over that same pair.

defineModel() is a compiler macro (available only inside <script setup>; outside it, the helper it compiles to — useModel(props, 'modelValue') — does the same job once you declare the prop and emit yourself) that, for one declaration, generates:

A prop (modelValue by default, or a name you choose) added to the component's props, exactly as if you'd written it in defineProps.
An emit (update:modelValue) added to the component's emits, exactly as if you'd written it in defineEmits.
A computed-like ref that reads the prop and, when written to, fires the emit — the same get/set relationship you'd otherwise write by hand.

The one behavior that isn't just "the same thing, shorter": if the parent doesn't bind that prop at all, the ref defineModel returns doesn't stay undefined and read-only the way a plain prop would. It falls back to behaving like an ordinary local ref, seeded with whatever default you gave it, fully writable, with no parent to sync to. That fallback is what makes defineModel usable for genuinely optional two-way bindings — a component with a sensible built-in state that a parent can optionally take over.

Building It Up: How defineModel Actually Works

The basic case

<!-- CurrencyInput.vue -->
<script setup>
const model = defineModel({ default: 0 })
</script>

<template>
  <input type="number" v-model.number="model" />
</template>

<!-- Parent.vue -->
<script setup>
import { ref } from 'vue'
import CurrencyInput from './CurrencyInput.vue'

const price = ref(19.99)
</script>

<template>
  <CurrencyInput v-model="price" />
</template>

Key concept: model inside CurrencyInput and price inside the parent are two different refs kept in sync by the prop/emit pair defineModel wrote for you. Mutating model.value inside the child doesn't reach across the component boundary directly — it emits, and the parent's v-model catches that emit and writes price.value for you.

Options: default, required, and type

defineModel takes the same options a prop does, because under the hood it is one:

// A required model — TypeScript removes `undefined` from its type for you.
const model = defineModel<string>({ required: true })

// An optional model with a default, typed explicitly.
const model = defineModel<string | undefined>({ default: 'Untitled' })

Typing it explicitly matters: an untyped defineModel() in a .vue file with <script setup lang="ts"> infers as loosely as an untyped prop would, so name the type rather than relying on inference from a call site that doesn't exist yet.

Multiple, independent named models

A component can expose more than one two-way binding by naming each defineModel call — this is the same v-model:propName syntax Vue has supported since named component v-models existed, now paired with the macro instead of hand-written props and emits:

<!-- NameFields.vue -->
<script setup>
const firstName = defineModel('firstName', { default: '' })
const lastName = defineModel('lastName', { default: '' })
</script>

<template>
  <input v-model="firstName" placeholder="First name" />
  <input v-model="lastName" placeholder="Last name" />
</template>

<template>
  <NameFields v-model:first-name="first" v-model:last-name="last" />
</template>

Key concept: each named defineModel call is its own independent prop/emit pair. There's no shared state between firstName and lastName beyond what your component logic adds — they're two separate contracts, not one contract split in two.

Modifiers, and transforming the value

A parent can attach modifiers to any v-model, same as v-model.trim on a native input. Read them by destructuring the second value defineModel returns, and use get/set to act on them:

<!-- TitleField.vue -->
<script setup>
const [model, modifiers] = defineModel({
  set(value) {
    return modifiers.capitalize && typeof value === 'string'
      ? value.charAt(0).toUpperCase() + value.slice(1)
      : value
  },
})
</script>

<template>
  <input v-model="model" />
</template>

<template>
  <TitleField v-model.capitalize="title" />
</template>

🎮 Try it yourself

▶️ Open the interactive playground →

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

Edge Cases and Gotchas

Object and array defaults need a factory, not a literal. This is the same rule as a regular prop default, and it's easy to forget because defineModel({ default: 0 }) looks so much like a plain value assignment: default: [] hands every instance without a bound value the same array, so mutating it in one unbound instance leaks into every other. Use default: () => [] instead.

No parent binding means a local ref, not undefined. This is the behavior that makes defineModel genuinely different from a plain required-less prop, and it's also the one detail worth testing explicitly: a component you render without v-model at all should still work, driven entirely by its own default. Vue 3.4.1 extended the fallback to parents that pass the prop one-way, without an update: listener, so on 3.5 it's simply the documented behavior, not a caveat to work around.

A default plus a parent bound to undefined desyncs. With <Child v-model="myRef" /> and myRef = ref(), the child shows its default while the parent's myRef stays undefined until the child writes. The Vue docs call this out as a warning: if the parent binds the model, give its ref a real starting value rather than leaning on the child's default.

Don't declare the same prop name in both defineProps and defineModel. defineModel('title') already declares a title prop. List title in defineProps too and the compiler won't complain — it merges both, and defineModel's options silently replace yours for that key. Any prop that isn't part of a v-model binding still belongs in an ordinary defineProps.

get runs on every read; set runs only when the component itself assigns model.value. Values arriving from the parent never pass through set, and with no parent binding set's return value is only emitted — the local ref keeps the raw value. Keep both transforms pure and cheap — no side effects, no async work. They're formatting hooks, not lifecycle hooks.

Modifiers on an unnamed model and a named model are separate namespaces. v-model.trim sets modifiers for the default (modelValue) model; v-model:title.trim sets modifiers scoped to the title model only. Destructure the modifiers from the matching defineModel call, not a shared object.

Best Practices

Reach for defineModel for anything inherently two-way — form controls, toggles, a value the child both displays and edits. It's the direct replacement for the old computed get/set pattern, not a new category of API.
Prefer named models over overloading one modelValue the moment a component genuinely exposes more than one independent piece of editable state. Two named models are clearer than one object-shaped model the child has to destructure.
Type every defineModel explicitly in TypeScript. An inferred type from a macro with no call-site arguments is easy to get wrong silently; write defineModel<string>() rather than leaning on inference.
Don't use v-model to fake a read-only prop. If the child never writes back, it's a normal prop, not a model — v-model signals "this can flow both ways," and using it where that's untrue misleads the next person who reads the parent's template.
Don't wire defineModel straight into a Pinia store. v-model is a parent/child contract; a store is global state. Write to store actions directly and keep the two mechanisms separate, or you'll end up debugging which one actually owns the value.

FAQ

Does `defineModel` replace `defineProps` entirely?

No. It only replaces the declaration for props that participate in a v-model binding. Every other prop on the component still goes in an ordinary defineProps.

Can I use `defineModel` outside `<script setup>`?

Not the macro itself — it only exists inside <script setup>. But the helper it compiles to, useModel() (3.4+), works in a plain setup(): declare the prop and update: emit yourself, then const model = useModel(props, 'modelValue').

Why does `v-model` on my component silently do nothing?

Before defineModel, this was almost always a mismatched prop/emit name — modelValue declared in props but update:modalValue (typo) in the emit, or vice versa. defineModel removes that failure mode entirely, since one declaration generates both sides. If it's still not updating, check that the parent binds the name you declared (v-model:title for defineModel('title')), and that you haven't re-declared the prop in defineProps — that compiles silently and defineModel's options replace yours.

Do I need to add the model's event to `defineEmits` as well?

No — defineModel declares the prop and the emit for you. Adding the same event again in defineEmits is redundant but harmless — the compiler merges both lists.

Is `defineModel` available in Vue 2?

No. Vue 2 has no compiler macro for this; components there declare value/input (Vue 2's default model event, before the modelValue/update:modelValue convention Vue 3 introduced) by hand, and that pattern doesn't change in the Vue 2 line. Treat any Vue 2 example that mentions defineModel as a mistake, not a version difference.

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

Cheat Sheet

Task	Code	Notes
Basic model	`const model = defineModel()`	Prop `modelValue` + emit `update:modelValue`, generated
With default	`defineModel({ default: 0 })`	Object/array defaults need a factory: `default: () => []`
Required	`defineModel<string>({ required: true })`	Removes `undefined` from the TS type
Named model	`defineModel('title')`	Parent binds with `v-model:title`
Multiple models	`defineModel('a')` + `defineModel('b')`	Fully independent prop/emit pairs
Read modifiers	`const [m, mods] = defineModel()`	`mods.yourModifier` is `true` when the parent adds `.yourModifier`
Transform value	`defineModel({ get(v) {…}, set(v) { return … } })`	`set` runs on the child's writes (its result is what's emitted); `get` runs on every read
No parent binding	(default behavior)	Ref falls back to a local, fully writable ref seeded by `default`

<script setup lang="ts">
// The full pattern: a required, typed, transformed model with modifiers.
const [model, modifiers] = defineModel<string>({
  required: true,
  set(value) {
    return modifiers.trim ? value.trim() : value
  },
})
</script>

<template>
  <input v-model.trim="model" />
</template>

Key Takeaways

v-model on a component is always a prop plus an event; defineModel doesn't change that contract, it generates it.
With no parent binding, defineModel's ref becomes a local, writable ref seeded by your default — not undefined.
Independent two-way bindings are named models (defineModel('name')), each its own prop/emit pair.
Modifiers arrive as the second destructured value; transform the model with get/set, not a watcher.
The same prop rules still apply underneath: factory functions for object/array defaults, explicit typing in TypeScript.

The typo-prone emit dance from the top of this article is gone, but that was never the interesting part. v-model was never magic to begin with — it was always a prop and an event, wired by convention. defineModel just means you stop wiring it by hand, and everything you now know about that contract still applies exactly where the macro can't reach: get/set transforms, multiple named models, and the one moment it quietly falls back to a local ref.

What's the messiest custom v-model you've had to debug — a typo'd event name, a shared object default, or something else entirely? Drop it 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___

`beforeunload` Can Still Kill Your bfcache. Mount It Only When Dirty.

Parsa Jiravand — Mon, 05 Oct 2026 06:10:30 +0000

Hit the back button on most sites and the previous page just reappears — no spinner, no white flash, no network tab lighting up. It was never gone. The browser froze it in memory instead of throwing it away.

Then one day, on your own app, it stops being instant. Same page, same back button, now with a full reload every time. Nobody touched the router. Somebody added a "you have unsaved changes" warning.

What "instant" actually is

That instant restore has a name: the back/forward cache, or bfcache. When you navigate away, instead of destroying the page, the browser can suspend it whole — DOM, JavaScript heap, running timers, scroll position, all of it — and hand it straight back if you hit back or forward. No HTML re-parse, no JS re-execution, no re-fetch. It just un-pauses.

Safari and Firefox have shipped some form of this for a very long time. Chrome was the holdout — for years it only cached in narrow cases — until it rolled out broad bfcache support starting with Chrome 96 in late 2021. Today, on a site that qualifies, back and forward navigation across all three engines can be effectively instant.

"On a site that qualifies" is doing a lot of work in that sentence. Plenty of real apps don't, and most of the time nobody notices, because nothing announces the miss. The page just... loads normally, the way it always has. You only notice the regression if you had bfcache and lost it.

The listener that looks harmless

Say your app has a form, and you don't want people losing work by fat-fingering the back button. The standard move:

window.addEventListener('beforeunload', (e) => {
  if (hasUnsavedChanges) {
    e.preventDefault();
    e.returnValue = '';
  }
});

Reasonable. It only shows the native "leave site?" prompt when hasUnsavedChanges is true. Surely an idle listener that does nothing most of the time can't cost anything?

For a long time, in the browsers that enforced this most strictly, it could. The check happened at navigation time, before your callback ever ran — so the browser couldn't know whether this departure was one where the handler would actually intervene. It only knew a beforeunload handler existed, and an always-mounted one is a standing promise the page might need to act on the way out, which a suspended, un-runnable page can't keep. So the listener being registered at all — not what it did on any given visit — was what counted against you.

That specific rule has been shifting. Some engines have relaxed how much a mere beforeunload registration costs you; others still treat it as a real risk. Which means you can't safely assume either behavior for the whole spread of browsers and versions your users are actually running — and the fix costs nothing regardless of which way today's browser leans.

unload doesn't get the benefit of that ambiguity: it's the one still widely documented as a reliable disqualifier, in some engines for the page's whole lifetime, listener present or not, browser-relaxation or not.

Open Chrome DevTools → Application → Back/forward cache, and click "Test back/forward cache." It runs the browser's own eligibility check and names the specific not-restored reasons for your page, on your browser version — which beats guessing from an article, this one included.

The fix isn't deleting the warning

The warning is legitimate — you don't want to silently lose someone's draft. What's fixable is when the listener exists, not whether it does.

function updateUnsavedGuard(hasUnsavedChanges) {
  if (hasUnsavedChanges) {
    window.addEventListener('beforeunload', warnOnLeave);
  } else {
    window.removeEventListener('beforeunload', warnOnLeave);
  }
}

function warnOnLeave(e) {
  e.preventDefault();
  e.returnValue = '';
}

Attach it only while there's something to lose, and detach it the moment the draft is saved. A page with no unsaved changes has no listener mounted, so it's eligible for bfcache the rest of the time — which, for most forms, is nearly always.

🎮 Try it yourself

▶️ Open the interactive playground →

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

For cleanup that isn't about a warning dialog — closing a WebSocket, cancelling a poll, flushing analytics — reach for pagehide instead of unload. unload is the one without the ambiguity: some engines disqualify a page from bfcache just for having an unload listener anywhere on the page, for its whole lifetime, warning or not.

window.addEventListener('pagehide', (event) => {
  socket.close();
  clearInterval(pollTimer);
  // event.persisted === true means the page is being frozen for bfcache,
  // not destroyed — the same handler covers both cases safely.
});

window.addEventListener('pageshow', (event) => {
  if (event.persisted) {
    // restored from bfcache, not a fresh load — the socket you closed
    // in pagehide is gone, so reopen it and refresh anything time-sensitive.
    socket = reconnect();
    refreshStaleTimestamps();
  }
});

pageshow fires on every page load, fresh or restored — event.persisted is the flag that tells you which one just happened. That's the piece most cleanup code is missing: it assumes a fresh mount and re-runs setup that a restored page already has, or it never notices the page came back at all and sits there with a closed socket and a timestamp from ten minutes ago.

What you get back

Fix both, and the back button goes back to being boring: instant, no flash, no waterfall in the network tab. The unsaved-changes prompt still fires when it should — it's just not paying rent on every page for the whole time your form is untouched. And a restored tab reconnects its socket and refreshes its stale data instead of quietly pretending nothing happened while it was away.

One more worth a mention, since it's not a listener at all: a Cache-Control: no-store header used to disqualify a page from bfcache outright, no JavaScript involved. Chrome has since relaxed that — a no-store page can now enter bfcache as long as the user's cookies and Authorization state don't change while it's parked (either one evicts it immediately, and it gets a shorter hold than a normal bfcache entry regardless), though a no-store page that also keeps a WebSocket, WebTransport, or WebRTC connection open still gets excluded outright. Outside the no-store case, Chrome has separately stopped treating an open WebSocket as an automatic blocker on its own — since Chrome 149, it closes the socket on the way out and hands you an onclose/pageshow to reconnect from, instead of refusing to cache the page at all. WebTransport and WebRTC didn't get the same carve-out; they still block bfcache outright, with or without no-store. All of this is Chrome-specific and recent, so don't assume it holds in every engine or for every connection type — if your listeners are clean and bfcache still won't take, check this header (and what's still open) and verify the current behavior in DevTools rather than trusting any rule, old or new, by default.

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

Open DevTools → Application → Back/forward cache on your own site and click "Test back/forward cache." What comes back — and were you expecting it?

📚 Read next

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

Thanks for reading! Let's stay connected:

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

DEV Community: Parsa Jiravand

Nuxt 4 Migration: The Breaking Changes That Actually Bite

What you'll learn

Who this is for

Table of contents

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

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

Will my app silently return wrong data after upgrading?

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

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

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

Cheat sheet

Key takeaways

🎮 Try it yourself

🧠 Test yourself

📚 Read next

Your Lighthouse Score Is 100. Long Animation Frames Explain the Jank.

The wrong way: squinting at a flame chart for a name that isn't there

The real diagnosis: the frame, not just the task

The fix, once you know what you're fixing

Why this matters beyond one button

The honest caveat

🎮 Try it yourself

🧠 Test yourself

📚 Read next

React 19.3 Fragment Refs: Skip the Wrapper Div for a Ref

What you'll learn

Who this is for

Table of contents

The problem: a ref has nowhere to live

The mental model

Stage 1: a ref on a Fragment

Stage 2: group-level event listening

Stage 3: observing the group with observeUsing

Stage 4: focus management across the group

Stage 5: measuring and scrolling the group

Edge cases and gotchas

Best practices: when to reach for this

FAQ

Can I pass a ref to the <>...</> shorthand?

Does a Fragment Ref add anything to the DOM?

Will a click on a deeply nested element still reach a Fragment's addEventListener?

Do I need anything beyond react-dom 19.3?

Does the React Compiler change how Fragment Refs behave?

Cheat sheet

Key takeaways

🎮 Try it yourself

🧠 Test yourself

📚 Read next

You Added `will-change` to Fix the Jank. You Made It Worse.

The rule that's correct on one element and wrong on two hundred

Why the wrong lesson feels right

The mental model that actually holds up: a promise, not a setting

🎮 Try it yourself

When the old way — no will-change at all — is the right call

The honest caveat

The takeaway

🧠 Test yourself

📚 Read next

You're Animating for Everyone. `prefers-reduced-motion` Fixes That.

The fix that breaks the loading spinner

Decorative motion and motion that's doing a job

Why no-preference is the one to reach for

The part CSS can't fix for you

🎮 Try it yourself

The honest caveat

The takeaway

🧠 Test yourself

📚 Read next

Stop Losing Promise Errors. `unhandledrejection` Catches Them.

The code that looks finished

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

Can I pass a ref to the `<>...</>` shorthand?

When the old way — no `will-change` at all — is the right call

Why `no-preference` is the one to reach for

Stage 3: deciding who gets blocked, with `htmlLimitedBots`

Does `generateMetadata` run before or after my page component?