DEV Community: Eve

Vue 3 Cleans Up After Itself — Until It Can't

Eve — Tue, 15 Sep 2026 13:38:13 +0000

Originally published at eveko.dev.

Vue 3 disposes the reactive effects it creates. A watch or a watchEffect declared in <script setup> is bound to the component instance and torn down the moment that component unmounts — no cleanup code required. So the memory leaks that reach production mostly don't live in the reactivity system. They live in the gap between what Vue owns and what a developer hands to something that outlives the component.

A user opens the reports view, goes back to the list, and opens it again. Each visit starts a setInterval polling every five seconds; each exit leaves it running. Nothing ever stops them, so the pollers accumulate across the day — every one still firing, every one still holding the response it fetched last, and the tab's footprint climbing from morning onward. By afternoon the filter box has started to stutter. A second failure class is louder. On a memory-constrained tab (a mid-range Android, an embedded webview, a TV browser) the page doesn't get slow. The browser kills it.

Both failures trace to the same root, and it isn't Vue. A 2026 static-analysis pass across 500 public repositories (the StackInsight study) convicts the unglamorous resources. It is self-published, its detectors adapted from the author's own commercial scanner (Code Evolution Lab, which the page also pitches), and it admits that formal precision and recall were never measured. Of the 15,750 leak sites it flagged in Vue repositories, the Vue-specific "missing watch stop handle" pattern accounts for roughly a quarter, though that detector flags uncaptured stop handles — including synchronous setup() watchers that Vue disposes anyway. Nearly everything else is a resource Vue never owned rather than anything its reactivity system created. The reactivity system Vue developers are drilled to fear is the smaller share of the problem.

This is a field guide to where Vue 3 leaks actually come from, and the one rule that prevents all of them. One thing is out of scope. Server-side leaks (Nuxt SSR contexts, request-scoped store state that never gets garbage-collected between requests) are a genuinely different problem with a different shape; Vue's SSR guide covers the mechanism as cross-request state pollution, and Nuxt's state-management docs indict the module-scope ref as the specific trap. Start with those. Confirming that a tab is leaking at all, rather than just using memory, is a skill of its own; that comes near the end.

Vue already cleans up the part everyone worries about

The mental model worth carrying is one sentence: Vue disposes the effects it owns, and owns nothing else.

Every component's setup() runs inside an effect scope, an internal container that collects the reactive effects created during synchronous execution. The official docs insist on it: watchers "declared synchronously inside setup() or <script setup> are bound to the owner component instance, and will be automatically stopped when the owner component is unmounted. In most cases, you don't need to worry about stopping the watcher yourself" (per the Vue watchers guide). A watch that fires on every store mutation, a watchEffect that re-runs on every keystroke — both vanish cleanly on unmount, because Vue was holding the handle the whole time.

A computed reaches the same place by a different route. Since 3.5 it isn't registered on the scope at all; it drops its dependencies once it loses every subscriber, and the maintainers deny it needs stopping at all: a post-3.5 computed is, in their words, "self-disposing" (per vuejs/core#11886). Either way, nothing is left for you to stop.

So the reactivity system is not the threat. The threat is everything Vue never saw you create. Three categories cover almost all of it:

Manual browser APIs — setInterval, addEventListener, requestAnimationFrame, IntersectionObserver, WebSocket. Vue doesn't wrap these. It doesn't know they exist.
Third-party library instances — a chart, a map, a rich-text editor. Each holds its own canvases, listeners, and buffers.
References handed to something longer-lived — a module-scoped array, a global event bus, a Pinia store that keeps pushing component data and never lets go.

The skeptic dismisses the whole exercise by paragraph three: isn't this just "clean up after yourself," the same discipline every framework and vanilla page has always demanded? Partly, yes — the principle is universal. What's specific to Vue 3 is the part it handles for free (the owned effects, disposed without a line of cleanup code) and the seams it gives you for the rest: onUnmounted, onScopeDispose, effectScope, onWatcherCleanup. The principle is old. The tools are new, and most of this article is about using them.

Where the leaks actually live

The StackInsight study ranked all 55,864 of its flagged leak sites by category. These are the top five of nine, counted across the full React/Vue/Angular corpus; the shape of the ranking is the whole argument:

Category	Share of leak sites
Missing timer cleanup	43.9%
Missing event listener removal	19.0%
Missing subscription cleanup	13.9%
Missing effect cleanup	9.3%
Missing watch stop handle	7.1%

One row needs unpacking before the shape reads correctly. Missing watch stop handle is a Vue-only detector, so its 7.1% is measured against a corpus that is roughly seventy per cent React and Angular; against Vue's own 15,750 findings, the same pattern is about a quarter. The study concedes the skew plainly: the sample was "weighted toward React".

This is a single study, not a law of nature, but the direction is hard to argue with. The top three rows, the ones Vue's auto-disposal does nothing for, are more than three-quarters of the corpus. Inside Vue's own findings, three of every four flagged sites are something other than the watcher pattern. The ranking quietly mocks the priorities most leak articles encode. A developer who memorizes the entire effectScope API and still writes setInterval without clearInterval has optimized the quarter and shipped the rest. The tooling asymmetry matches: eslint-plugin-vue ships vue/no-watch-after-await in its essential preset, which reports a watch registered after an await, and ships nothing at all for a setInterval that never gets cleared. Closing that gap is a house rule, not a plugin install: @eslint-react's web-api-no-leaked-interval does check that a setInterval is paired with a clearInterval, but reports only inside useEffect callbacks and stays silent in onMounted. What a Vue team can enforce is a no-restricted-syntax selector catching the shape that is unfixable rather than merely unfixed: a setInterval whose return value is discarded, leaving no id for any clearInterval to take. That bans one call; it never proves a teardown, because a selector cannot tie a clearInterval to the id a particular setInterval returned.

So the rest of this is organized by what Vue can't see, roughly in order of how often it bites.

Manual browser resources: timers, listeners, subscriptions, observers

These share one fix: whatever you start in onMounted, stop in onUnmounted. The interesting part is the ways the stop quietly fails to happen.

Start with listeners, because the failure has a sharp edge most people hit once. Watch the handler reference across the two calls.

Avoid:

onMounted(() => {
  window.addEventListener('resize', () => layout(window.innerWidth))
})

onUnmounted(() => {
  // a second arrow — a different function, so this removes nothing
  window.removeEventListener('resize', () => layout(window.innerWidth))
})

Prefer:

function onResize() {
  layout(window.innerWidth)
}

onMounted(() => {
  window.addEventListener('resize', onResize)
})

onUnmounted(() => {
  window.removeEventListener('resize', onResize)
})

The avoid version is unfixable, not just unfixed. removeEventListener matches by reference, and its cleanup call removes nothing: the second arrow is a different function from the first, however identical the two look. The window outlives the component, so the listener (and the layout closure behind it) stays registered for the life of the tab. Every remount adds another, and each one still fires. After a dozen visits a single resize event runs layout a dozen times, eleven of them on behalf of components that no longer exist.

Observers and sockets are the same story with a different verb. An IntersectionObserver watching a sentinel for infinite scroll keeps its target (and the component scope around it) alive until you disconnect().

Avoid:

const observer = new IntersectionObserver(onIntersect)

onMounted(() => {
  observer.observe(sentinel.value)
})

Prefer:

const observer = new IntersectionObserver(onIntersect)

onMounted(() => {
  observer.observe(sentinel.value)
})

onUnmounted(() => {
  observer.disconnect()
})

A WebSocket wants close(), an EventSource wants close(), a ResizeObserver wants disconnect(), a requestAnimationFrame loop wants cancelAnimationFrame. Same rule, same seam. Timers, the most common leak in the study's corpus, get the canonical treatment in the recommendation block below; the fix is clearInterval, and the trap is forgetting that the interval's callback keeps its entire closure alive between ticks.

The two watcher leaks

Watchers leak in two distinct ways, and conflating them is why the advice around them is muddled. Only one is the reactivity system's.

The first leak isn't the watcher — it's what the watcher starts. A watcher that opens a socket, registers a listener, or fires a request on every change, without tearing down the previous one, stacks resources on each run. The rule worth memorizing: if a watcher starts something (a listener, a request, a timer), it must also stop it. Vue 3.5 added onWatcherCleanup for exactly this: a teardown that runs when the watcher is invalidated and about to re-run (per the Vue docs on side effect cleanup). It fires on the way out, too. Vue registers the cleanup as the effect's onStop hook, so unmounting the component closes the last socket as well as every one superseded mid-flight.

Avoid:

watch(roomId, (id) => {
  const socket = openSocket(id)
  socket.onMessage(handleMessage)
})

Prefer:

import { watch, onWatcherCleanup } from 'vue'

watch(roomId, (id) => {
  const socket = openSocket(id)
  socket.onMessage(handleMessage)
  onWatcherCleanup(() => socket.close())
})

onWatcherCleanup lands in Vue 3.5+, and it has to be called during the watcher's synchronous execution — never after an await. On older versions, and past that constraint, the third callback argument (onCleanup) binds to the watcher instance instead. When the side effect is a fetch, the cleanup is an AbortController, and the same cleanup seam carries it — the deeper mechanics of racing requests get their own treatment in the piece on cancelling API requests in Vue 3, but nothing in this section waits on it. The leak angle is the simpler half: started, so stop it.

The second leak is the only one that actually lives in the reactivity system, and it's narrow. A watcher created asynchronously (after an await, inside a setTimeout, in a promise callback) is never bound to the component, so it never auto-stops. The same guide rejects any ambiguity: a watcher created in an async callback "won't be bound to the owner component and must be stopped manually to avoid memory leaks."

The honest first move is to not create watchers asynchronously at all — hoist them into synchronous setup and the auto-disposal does the work. When the timing genuinely can't be helped, capture both handles (the timer's and the one watchEffect returns) and clear them on unmount. The broken shape first:

Avoid:

onMounted(() => {
  setTimeout(() => {
    watchEffect(() => {
      document.title = `Unread: ${unread.value}`
    })
  }, 1000)
})

Prefer:

let timeoutId
let stop

onMounted(() => {
  timeoutId = setTimeout(() => {
    stop = watchEffect(() => {
      document.title = `Unread: ${unread.value}`
    })
  }, 1000)
})

onUnmounted(() => {
  clearTimeout(timeoutId)
  stop?.()
})

The timer is the easy half to forget: unmount before it fires and there is no watcher to stop yet, only a callback still queued to create one.

Handles and references that outlive the component

Two leak sources left, and they're the ones Chrome's heap snapshot tends to surface as "detached" nodes.

Third-party widgets allocate aggressively — a charting library holds canvases, its own resize listeners, and the dataset you handed it. Vue mounts and unmounts the wrapper component; the library instance underneath neither knows nor cares. The pattern is mechanical: store the instance, call its teardown method on unmount.

Avoid:

let chart

onMounted(() => {
  chart = new Chart(canvas.value, config)
})

Prefer:

let chart

onMounted(() => {
  chart = new Chart(canvas.value, config)
})

onUnmounted(() => {
  chart.destroy()
})

The subtler source is a reference you park somewhere long-lived. Module scope is the classic trap: a const at the top of a file outlives every component that imports it, so anything put into it and never removed grows for the life of the tab. The same applies to a global event bus you never off(), or a store array that accumulates component data without bound. Module scope in its plainest form is a cache nobody ever prunes:

Avoid:

// module scope — and nothing ever removes an entry
const history = new Map()

export function useHistory(key, entry) {
  history.set(key, entry)
}

Prefer:

import { onScopeDispose } from 'vue'

// same Map, same signature — the only change is registering the teardown
const history = new Map()

export function useHistory(key, entry) {
  history.set(key, entry)
  onScopeDispose(() => history.delete(key))
}

onScopeDispose rather than onUnmounted here, because useHistory is a composable and a composable can run in a scope that is not a component's. Swapping the Map for a WeakMap is no substitute for that teardown: WeakMap keys must be objects or non-registered symbols, so a string or numeric key throws a TypeError, and an object key only hands the entry's release to the collector's schedule instead of unmount. A weak collection fits where the key is an object whose lifetime something else already owns; here it is an identifier the caller supplies.

The same long-lived-reference trap shows up in Pinia's own $subscribe and $onAction. The safe case is the default: registered inside an active effect scope — a component's setup() included — both bind to that scope and are removed when it disposes (per the Pinia docs on state and actions). Detach them ({ detached: true } on $subscribe, true as the second argument to $onAction), or register them where no scope is active, and the returned unsubscribe function becomes yours to call. The flag is the whole difference:

Avoid:

const cart = useCartStore()

// detached opts out of the scope cleanup — and nothing replaces it
cart.$subscribe(saveCart, { detached: true })

Prefer:

const cart = useCartStore()

// no detach: the subscription dies with the scope that registered it
cart.$subscribe(saveCart)

A reference parked in long-lived scope has a second failure mode: a handler that closes over a template ref keeps that DOM node detached-but-alive, out of the garbage collector's reach after unmount. The reference is the leak. Clear it when the component goes; when there is no component, the next section supplies the hook.

Composables: give the effects a scope to die with

Composables complicate the mental model in one specific way. onUnmounted needs a component instance; onScopeDispose needs an effect scope. Every component setup is a scope, but not every scope is a component — a composable can just as easily run inside a Pinia store's setup or a hand-rolled effectScope(), where there is no instance of its own for onUnmounted to bind to. A composable that relies on onUnmounted for teardown is betting on a component being there to hold it.

onScopeDispose is the fix: it registers teardown on the current effect scope rather than the component instance, so it fires for any scope — component setup or otherwise. The docs frame it as "a non-component-coupled replacement of onUnmounted in reusable composition functions" (Reactivity API: Advanced). One limit rides along: the scope has to be active. Outside any scope at all — module top level, a router guard, a Vue plugin's install() — it registers nothing and warns in dev only, silently in production, exactly as onUnmounted does. Neither hook rescues that case; code that runs there owns its teardown outright.

Avoid:

export function useSocket(url) {
  const socket = new WebSocket(url)
  onUnmounted(() => socket.close())
  return socket
}

Prefer:

import { onScopeDispose } from 'vue'

export function useSocket(url) {
  const socket = new WebSocket(url)
  onScopeDispose(() => socket.close())
  return socket
}

And when a composable spins up several effects that should be disposed as a unit (or you need reactivity outside any component), tracking each stop handle by hand is the trap effectScope exists to remove. It's the same machinery the RFC authors lifted out of Vue's component internals precisely because, outside a component, "it's laborious to manually collect all the effects" and "easy to forget", which "might result in memory leakage" (per RFC 0041). Watch how many handles the caller has to remember in the first version.

Avoid:

// every effect returns its own stop handle, tracked by hand
const stopSync = watch(source, sync)
const stopReport = watchEffect(report)

function teardown() {
  stopSync()
  stopReport()
}

Prefer:

import { effectScope } from 'vue'

const scope = effectScope()

scope.run(() => {
  watch(source, sync)
  watchEffect(report)
})

function teardown() {
  // one call disposes every effect in the scope
  scope.stop()
}

The counter: "Vue cleans up, and VueUse handles the rest"

Skeptics deride all of this as solved-problem fear-mongering, and the objection comes in two parts worth taking seriously.

The first part is correct on the facts: Vue 3 does auto-dispose, so a category of older "always stop your watchers" advice is genuinely outdated. That much is granted. But auto-disposal covers a quarter of Vue's flagged sites, not the three-quarters that were never Vue's to dispose — and not even all of that quarter, since the async-registration case sits inside it and auto-disposal never reached there either. The auto-disposal that practitioners cite as the reason not to worry is doing nothing for the timers, listeners, and subscriptions on the other side of that line. This is the design verdict, and it isn't a knock on Vue: no framework can reclaim a resource it never saw allocated. The framework concedes that boundary by design. Auto-disposing owned effects is the right call. It just bounds the problem to exactly the resources Vue has a handle on, and leaves the rest to you by necessity, not oversight.

The second part is the better argument: don't hand-roll any of this; reach for VueUse, whose composables wire teardown in for you. It's the right default, not a crutch. useEventListener registers on mount, and its docs vouch for the behavior plainly: it runs "removeEventListener automatically on unmounted". useIntervalFn does the same for timers, though you have to read its source to see why: it hands pause straight to tryOnScopeDispose.

import { useEventListener, useIntervalFn } from '@vueuse/core'

useEventListener('resize', onResize)
useIntervalFn(refresh, 5000)

That's the listener section and the polling interval, both deleted. No onMounted, no onUnmounted, no reference-matching trap, no timer id to keep. The rule still matters, because the library is the rule applied, not a substitute for understanding it. Both composables tie their teardown to the current effect scope (the same seam this article is about), and the protection ends at the edge of what VueUse wraps. The niche charting library, the module-scoped cache: the moment a developer touches a resource no composable covers, they own teardown again, and the quiet assumption that VueUse must have handled it is how that leak ships. Reach for VueUse. Understand why it works.

Detection: confirm the leak before you chase it

Suspecting a leak and proving one are different activities, and the gap between them is where hours disappear. The recognition signal is blunt: mount a component, unmount it a dozen times, and if its instances are still in the heap after garbage collection, something is holding them. Reaching for Vue DevTools first is a dead end: its Components tab walks the mounted tree and skips instances already unmounted, so a leaked instance is precisely the one thing it cannot show. The proof lives in Chrome DevTools' Memory panel, and the workflow is mechanical (per the Chrome DevTools heap-snapshot guide): take a snapshot, navigate into the suspect component and back out several times, take a second snapshot, and switch it to Comparison view. DevTools runs a garbage collection before every snapshot, so whatever is still standing in the second one is pinned by something. Filter the class list by "Detached" to find DOM kept alive by stale references, then read the Retainers pane to see exactly what's holding on.

For teams that want deterministic checks in CI, Meta's memlab automates the snapshot-diff loop; for ad-hoc debugging, the manual panel is the first thing to reach for.

Below memlab sits a cheaper rung: a unit test asserting the teardown ran. A green test vouches only for the call, not for the reclamation. It says clearInterval fired with the id setInterval handed back, which makes it a regression guard on a leak already found rather than a way to find one.

// @vitest-environment happy-dom
import { mount } from '@vue/test-utils'
import { expect, it, vi } from 'vitest'
import Poller from './Poller.vue'

it('clears its interval on unmount', () => {
  const setSpy = vi.spyOn(globalThis, 'setInterval')
  const clearSpy = vi.spyOn(globalThis, 'clearInterval')

  const wrapper = mount(Poller)
  expect(setSpy).toHaveBeenCalledOnce()

  wrapper.unmount()
  expect(clearSpy).toHaveBeenCalledWith(setSpy.mock.results[0].value)
})

Poller is any component that starts an interval in onMounted. Vitest defaults to a node environment, so mount needs happy-dom or jsdom switched on. Skip vi.useFakeTimers(): it replaces the timer globals, and installing it after the spies leaves them recording nothing. The setInterval assertion is what keeps the test honest, since without it a component that starts no timer at all passes. Restore the spies as well — vi.restoreAllMocks() in an afterEach, or restoreMocks: true — because vi.spyOn on an already-spied global hands back the same spy, and a second test in the file would inherit the first one's call log.

None of that watches production. The nearest thing to a field reading is performance.measureUserAgentSpecificMemory(): Chromium-only, still a WICG draft rather than a W3C standard, and rejected with a SecurityError unless the document is cross-origin isolated under COOP and COEP. Its predecessor performance.memory is deprecated and non-standard, not a fallback. The out-of-memory kill is observable only after the fact and only out-of-band: declare a crash-reporting or default endpoint in a Reporting-Endpoints header and the browser posts a crash report once the renderer is gone, tagged reason: "oom" when the browser knows why. That mechanism is Chromium-only and defined in no published specification, which is the state of the art rather than a recommendation. Nothing inside a page that just exhausted memory survives to report on itself, which is why Sentry's maintainers deny it is detectable from inside the SDK. That endpoint is the only signal that survives the kill.

What looks like a leak but isn't

Three patterns set off false alarms worth pre-empting. <KeepAlive> deliberately retains cached component state: its growth is the feature, not a leak. What it does change is where cleanup goes: a cached component is deactivated rather than unmounted, so anything that should stop while it's hidden belongs in onDeactivated. Development-mode memory growth from HMR is not a production signal. And a Pinia store that grows isn't Pinia leaking — it's holding exactly what the application told it to hold, which means the fix is in the code that parks data there, not in the store.

What to actually do

The discipline reduces to one habit: at the moment you create a resource, ask whether Vue can see it. If it can't, you own its end.

Best practice:

In general: Vue disposes the effects it owns. You own the teardown of anything you create that can outlive the component — if Vue can't see it, it can't clean it up. Reach for VueUse where it already wraps the resource; own the teardown where it doesn't. Two questions settle most rows below: what did you create, and whose scope does it die with — onUnmounted inside a component, onScopeDispose in any other effect scope a composable might run in. The exceptions are the two rows with a seam of their own: onWatcherCleanup for a side effect started inside a watcher, effectScope for several effects that must die as a unit. If <KeepAlive> caches the component, anything that should stop while it's hidden goes in onDeactivated — onUnmounted won't run until the cache drops it. Confirm the leak with a two-snapshot heap comparison before you chase it.

Case	Reach for
`setInterval` / `setTimeout` / `requestAnimationFrame`	`clearInterval` / `clearTimeout` / `cancelAnimationFrame` in `onUnmounted` — or VueUse's `useIntervalFn` for the timers
`window` / `document` / emitter listener	`removeEventListener` (or the emitter's `.off()`) with the same handler reference in `onUnmounted` — or `useEventListener`
`IntersectionObserver`, `WebSocket`, `EventSource`	`disconnect()` / `close()` in `onUnmounted`
A side effect started inside a watcher	`onWatcherCleanup` (3.5+), or the `onCleanup` third argument
A watcher or effect created after an `await` or in a callback	create it synchronously if you can — otherwise capture the returned stop handle and call it, plus `clearTimeout` on the pending timer if a timer is what queued it
A third-party widget instance	store the handle, call its `.destroy()` in `onUnmounted`
A composable that may run outside a component	`onScopeDispose` — it fires for any effect scope, not just component setup
Several effects to dispose as a unit, or reactivity outside any component	`effectScope` — one `.stop()` disposes every effect inside
Component data pushed into module / global / store scope	clear the reference in `onUnmounted` — or `onScopeDispose` if a composable is what parked it
A detached Pinia `$subscribe`	don't detach unless something outside the component owns its end — and then that owner calls the returned unsubscribe

The one pattern to keep in muscle memory, because timers are the case people forget most — and because it is exactly what useIntervalFn wraps when you reach for VueUse instead:

Avoid:

onMounted(() => {
  setInterval(refresh, 5000)
})

Prefer:

let id

onMounted(() => {
  id = setInterval(refresh, 5000)
})

onUnmounted(() => clearInterval(id))

It comes down to one reflex: noticing, at the instant of creation, whether the thing you just made is something Vue is holding or something you are. Vue closed the gap it could close. The rest of the gap has your name on it, and closing it was never a matter of memorizing more APIs. It's knowing, for everything you create, whose scope it dies with.

Sources

Cancelling API Requests in Vue 3 — eveko — companion piece on aborting in-flight requests, the canonical watcher side effect.
Chrome DevTools: Fix memory problems — Google — the Detached class filter for finding DOM kept alive by stale references.
Chrome DevTools: Record heap snapshots — Google — the two-snapshot Comparison workflow and the Retainers pane.
computed is no longer controlled by effectScope — vuejs/core issue #11886, 2024 — maintainer confirmation that a post-3.5 computed self-disposes rather than being stopped by its scope.
CrashReport — MDN — the out-of-band crash report, delivered to a Reporting-Endpoints target after the renderer is gone.
ESLint rule: no-restricted-syntax — ESLint docs — the selector-based fallback: it can ban a call, but matches one node and never a pair.
ESLint rule: vue/no-watch-after-await — eslint-plugin-vue — the essential-preset rule for asynchronously registered watchers.
ESLint rule: web-api-no-leaked-interval — @eslint-react — verifies setInterval/clearInterval pairing, but only inside useEffect, so it never fires on onMounted.
Frontend Memory Leaks: a 500-repository study — StackInsight, 2026 — leak-category prevalence data across 500 public repos, with per-framework finding counts.
Measure Memory API — WICG draft — a Draft Community Group Report, explicitly not a W3C Standard nor on the standards track.
memlab: JavaScript memory leak detector — Meta — automates the snapshot-diff loop for deterministic CI checks.
Nuxt State Management: best practices — Nuxt docs — why a module-scope ref leaks across SSR requests; the out-of-scope neighbour of this article.
Performance.measureUserAgentSpecificMemory() — MDN — Chromium-only and experimental; rejects with SecurityError unless the document is cross-origin isolated.
Performance.memory — MDN — deprecated and non-standard; named here only to rule it out as a fallback.
Pinia: Actions — Pinia docs — $onAction binds to the component that registers it unless true is passed as the second argument.
Pinia: State — Pinia docs — $subscribe binds to the component that registers it unless detached.
RFC 0041: Reactivity effectScope — vuejs/rfcs — design intent behind effectScope and scope-bound disposal.
Vitest API: vi — Vitest docs — vi.spyOn on a global, and the timer globals useFakeTimers replaces.
Vitest: Test Environment — Vitest docs — node is the default; happy-dom or jsdom supplies the DOM that mount needs.
Vue core: reactivity/watch.ts — vuejs/core — watcher cleanups are registered as the effect's onStop hook, so they also run when the watcher stops.
Vue DevTools: Features — Vue DevTools docs — the documented panel list; no memory or retention panel among them.
Vue Test Utils: API reference — Vue Test Utils docs — mount, and the root wrapper's unmount() firing the component's unmounted hook.
Vue.js KeepAlive guide: lifecycle of a cached instance — Vue docs — a cached component is deactivated rather than unmounted; onActivated / onDeactivated are the hooks for that state.
Vue.js Reactivity API: Advanced — Vue docs — effectScope, getCurrentScope, onScopeDispose.
Vue.js SSR guide: cross-request state pollution — Vue docs — singleton state reused across requests on a long-running server process.
Vue.js Watchers guide — Vue docs — auto-disposal of synchronous watchers, async-callback trap, onWatcherCleanup.
VueUse: useEventListener — VueUse docs — listener registered on mount, removed automatically on unmount.
VueUse: useIntervalFn — VueUse docs — timer composable signature and its Pausable controls.
VueUse: useIntervalFn source — vueuse/vueuse — hands pause to tryOnScopeDispose, which is what clears the interval automatically.
WeakMap.prototype.set — MDN — WeakMap keys must be objects or non-registered symbols; anything else throws a TypeError.
Why Sentry cannot detect page crashes — getsentry/sentry-javascript issue #5280 — a maintainer's explanation that an OOM kill stops the SDK along with the page.

Cancelling API Requests in Vue 3: One Registry, Two Paths, and the Question That Orders Them

Eve — Tue, 28 Jul 2026 12:03:00 +0000

Originally published at eveko.dev.

Vue 3 exposes four things that look like four separate ways to cancel a stale request. The onCleanup parameter that watchEffect passes to its effect. The same parameter that watch passes to its callback. The onWatcherCleanup import shipped in Vue 3.5. And the AbortController that does the actual cancelling. They are not four ways — they are two registration paths over one cleanup registry, plus the single object that aborts the request. And one of those two paths silently stops working the instant an await runs: no exception, no production warning, just a stale request that resolves on its own schedule and overwrites fresher data. The fix for the request that won't cancel is knowing which path survives the await, not reaching for a newer API.

The three costs of a request nobody cancelled

Three different things break when a request outlives its relevance, and they are genuinely separate problems. Treating cancellation as a performance nicety dismisses the first one, which is the one that draws blood.

That first cost is correctness. A search field is bound to a watch; every keystroke fires a request. The user types k, ki, kit, kitt, kitte, kitten, kittens — seven requests, seven round-trips, no guarantee they return in order. The request for kit hits a slow replica and lands last. The watcher's callback runs with the kit payload, overwrites the kittens results already on screen, and the dashboard now shows results for a query the user finished typing two seconds ago. The URL still says kittens. Nothing threw. The official docs name this exact race: "what if id changes before the request completes? When the previous request completes, it will still fire the callback with an ID value that is already stale" (Vue watchers guide).

The second cost is wasted work, and it scales with traffic. Every abandoned request still ran. The browser opened the connection, the server ran the query, the bytes crossed the wire. One stale search is free. A dashboard that re-fires on every filter change, parked on a second monitor all day, is a steady drip of work nobody will read: bandwidth on the client, CPU and connection-pool slots on the server.

The third cost is resource lifetime, and it's the quietest. A request in flight pins memory until it settles: the promise, its closure, and the response-body buffer once headers arrive — all reachable, none collectable, until the fetch resolves or rejects.

One clarification before the mechanism, because the search-as-you-type framing invites it: cancellation is not debounce. Debounce decides whether to fire a request; cancellation decides what to do with the ones already in flight. They compose (debounce thins a storm of keystrokes to one request per pause, cancellation kills the previous request when the next one does fire), and a real search box usually wants both. Request deduplication (collapsing identical in-flight requests into one) is the third companion, and throttle (a cousin of debounce that a search box rarely needs) the fourth; dedup gets conflated with cancellation often enough that the library section below has to pull the two apart. The other place reactive fetching lives — <Suspense> with an async setup() — has its own cancellation story and stays out of scope here, and so does SSR: on the server the lazy watch callbacks that drive these fetches never fire, so request cancellation is a client-side concern.

The patterns that lost to `AbortController`

Browser request cancellation has a short, tangled history, and the current advice rests on knowing which of the old patterns to stop reaching for. XMLHttpRequest carried .abort() from the start, but almost nobody writes against XHR directly anymore. Axios shipped its own CancelToken, then deprecated it in 0.22 in favor of AbortController; code still carrying CancelToken is the clearest sign a cancellation path predates the 0.22 deprecation (October 2021) and is overdue for migration. Then there's the pattern that never went through a deprecation because it was never really an API: the staleness flag.

Plenty of hand-rolled search boxes still endorse the flag, and it's wrong in a way that matters. Watch the guard on the last line — it gates the render, not the request:

Avoid:

let latest = 0

watch(searchTerm, async (term) => {
  const requestId = ++latest
  const res = await fetch(`/api/search?q=${term}`)
  const data = await res.json()
  if (requestId === latest) results.value = data // stale responses get dropped here
})

The flag fixes correctness and nothing else. The stale request still ran to completion (the connection opened, the server did the work, the buffer filled), so two of the three costs survive. This article rejects the flag for exactly that reason. AbortController addresses all three, because it cancels the request itself rather than ignoring the answer. The one line readers misjudge is the catch:

Prefer:

watch(searchTerm, async (term, _prev, onCleanup) => {
  const controller = new AbortController()
  onCleanup(() => controller.abort())
  try {
    const res = await fetch(`/api/search?q=${term}`, { signal: controller.signal })
    results.value = await res.json()
  } catch (err) {
    if (err.name !== 'AbortError') throw err // aborting rejects the promise; that's expected, rethrow the rest
  }
})

Aborting an in-flight fetch rejects its promise with an AbortError, so the catch has to let that specific error pass and rethrow everything else — skip it and every cancellation surfaces as an unhandled rejection. Where the rethrown error surfaces (an error ref set in the catch, or an onErrorCaptured above) and how the loading state is shown are the component's concern, orthogonal to cancellation and left out of these examples. The pre-3.5 Nuxt recipe wired the same AbortController into useAsyncData and exposed a manual cancel function: same primitive, more plumbing.

With the canceller settled (it's AbortController, everywhere, now the de facto cancellation primitive), the only open question is where the controller.abort() registration lands so it actually fires. That's where the four names come in, and where 3.5 added a second path with a sharp edge.

Four names, two registration paths, one registry

Here is the whole map before the zoom-in. The four names collapse into three roles:

The canceller. AbortController and its signal. The only thing that actually stops a request. Settled above.
The parameter path. watchEffect passes an onCleanup function as the first argument of its effect; watch passes the identical function as the third argument of its callback. Same function, same registry, two entry points — one per watcher API.
The import path. onWatcherCleanup, imported from vue, added in 3.5. It registers into the same registry as the parameter, but finds its watcher a different way — and that difference is the whole article.

The signatures, from the reactivity API reference, show the shape but not the catch:

function watchEffect(
  effect: (onCleanup: OnCleanup) => void,
  options?: WatchEffectOptions
): WatchHandle

type OnCleanup = (cleanupFn: () => void) => void

function onWatcherCleanup(
  cleanupFn: () => void,
  failSilently?: boolean
): void

Both paths register the same kind of callback: something that runs right before the watcher re-runs, and again when the watcher is stopped. The onCleanup parameter and onWatcherCleanup are two doors into one room. The rest of this piece is about why one of the doors is sometimes locked.

The cleanup registry, keyed by the effect

Inside packages/reactivity/src/watch.ts, the cleanup callbacks for every watcher live in one structure (Vue core source). The key is the part to notice:

const cleanupMap: WeakMap<ReactiveEffect, (() => void)[]> = new WeakMap()

A WeakMap keyed by the effect, holding an array of cleanup functions per watcher. Because the key is the effect itself, the whole entry is garbage-collected when the watcher is; the registry can't leak the cleanups it holds. Register a cleanup and it's pushed onto that watcher's array. When the watcher re-runs, the array drains first; the source comment is blunt about it: "cleanup before running cb again." When the watcher is disposed, the same array runs through the effect's onStop. That's the entire lifecycle: run before next, run on stop.

Here's the toy version — one watchEffect, the cleanup wired through the first-argument parameter, no error handling or result use because the only thing on display is the wiring:

import { watchEffect } from 'vue'

watchEffect((onCleanup) => {
  const controller = new AbortController()
  onCleanup(() => controller.abort()) // load-bearing: register the abort the instant the controller exists
  fetch(`/api/user/${userId.value}`, { signal: controller.signal })
})

Every time userId changes, watchEffect re-runs: it drains the previous cleanup (which aborts the prior request), then runs the effect again with a fresh controller. The onCleanup parameter here is a closure. When watchEffect invokes the effect, it hands in a function that already knows which watcher it belongs to, because it was created bound to that watcher. Hold onto that word — bound. It's the difference between the two paths.

`onWatcherCleanup` stops working after the first `await`

onWatcherCleanup registers into that same array. It finds its watcher through a different mechanism, and that mechanism has an expiry. The docs admit the limit in a parenthetical: onWatcherCleanup "can only be called during the synchronous execution of a watchEffect effect function or watch callback function (i.e. it cannot be called after an await statement in an async function)" (reactivity API reference).

The reason is one module-level variable. In watch.ts, onWatcherCleanup defaults its owner to activeWatcher:

export function onWatcherCleanup(
  cleanupFn: () => void,
  failSilently = false,
  owner: ReactiveEffect | undefined = activeWatcher,
): void

activeWatcher is a single mutable binding (let activeWatcher: ReactiveEffect | undefined = undefined) that Vue sets when a watcher enters its synchronous phase and clears the moment that phase ends. A call before the first await sees the live watcher. A call after the await sees undefined, because the synchronous phase finished several microtasks ago. Watch where the registration sits relative to the await:

Avoid:

import { watch, onWatcherCleanup } from 'vue'

watch(userId, async (id) => {
  const controller = new AbortController()
  const res = await fetch(`/api/user/${id}`, { signal: controller.signal })
  const profile = await res.json()
  onWatcherCleanup(() => controller.abort()) // activeWatcher is already undefined — registers nothing
  applyProfile(profile)
})

That call registers nothing. With failSilently at its default, Vue emits a warning ("onWatcherCleanup() was called when there was no active watcher to associate with", from watch.ts), and in production that warning is stripped, so the call is a pure no-op. The controller never enters the registry, the previous request is never aborted, and every cost from the first section is back on the table. This isn't hypothetical: the open issue requesting clearer docs and worked examples for this after-await footgun (vuejs/docs #3222) was opened in April 2025 and is still open, which means the runtime still won't throw and the docs note remains the only guardrail. Since even that dev-time warning vanishes in production, the one thing that still catches the bug is a test: spy on abort() to assert the prior request is cancelled, or drive the out-of-order race and assert the fresher result isn't overwritten.

The blunt repair is to register during the synchronous phase, before the first await:

Prefer:

watch(userId, async (id) => {
  const controller = new AbortController()
  onWatcherCleanup(() => controller.abort()) // still inside the sync phase — registers fine
  const res = await fetch(`/api/user/${id}`, { signal: controller.signal })
  applyProfile(await res.json())
})

Move one line up and onWatcherCleanup behaves exactly as advertised.

None of this means 3.5 was wrong to ship the global. The onCleanup parameter carries a real ergonomic cost: it has to be threaded through the watcher's signature, and a cleanup that needs to be registered from inside a synchronous helper three calls deep can't reach the parameter unless every layer passes it down by hand. onWatcherCleanup solves precisely that — it pulls the active watcher from module state, so any synchronous code running under the watcher can register cleanup with no parameter in scope. That's a real ergonomic gain: the cleanup reads beside the effect, with nothing bolted onto the callback's signature to carry it there. 3.5 shipped a different tool with a different constraint, and the constraint is invisible until an await crosses it: onWatcherCleanup is the cleaner call in synchronous code and a trap in asynchronous code, exactly the code doing the fetching it's most often demonstrated with.

The parameter removes the ordering question from registration. Because it's the bound closure from the previous section, the docs are explicit that it "is bound to the watcher instance so it is not subject to the synchronous constraint of onWatcherCleanup" (Vue watchers guide) — it registers correctly whether it runs before or after an await, because there's no activeWatcher for it to miss.

Where a library earns the dependency

The strongest case against everything above is short: don't hand-roll cancellation at all. A data-fetching library already owns the registry, the signal, and the dedup, and a search box is the exact use case those libraries were built for. The counter insists the primitive is a waste of attention — and for the search box, it's mostly right.

VueUse's useFetch wraps an AbortController and re-runs on reactive source changes. Two of its options cancel. timeout aborts on a deadline; refetch is the one a search box wants — set it true and the previous request aborts automatically whenever the URL ref changes (VueUse useFetch source). The signal threading from the earlier examples disappears, and the library does it:

import { useFetch } from '@vueuse/core'

const url = computed(() => `/api/search?q=${searchTerm.value}`)
const { data } = useFetch(url, { refetch: true }).json() // aborts the in-flight request when `url` changes

That's genuinely less code than the hand-rolled watcher, and for cancellation it is precisely as much as the wrapper buys. useFetch does plenty else — interceptors, timeout, typed body helpers — but nothing resembling a query cache: no key, no shared in-flight registry, no module-level cache. Each call owns its own refs, so two components requesting the same URL fire two requests. What reads like deduplication is supersede. execute() opens by calling its own abort() before firing the next request (VueUse useFetch source), and killing the previous request is not collapsing two identical ones. Nothing in the documented option list claims otherwise. useFetch also exposes abort, canAbort, and aborted for wiring a manual Stop button — a different interaction than search-as-you-type, so it stays a mention rather than a contrived demo here.

One gap is worth naming, because the wrapper doesn't advertise it. useFetch aborts at the start of the next execute(): on URL change, on timeout, or when abort() is called by hand. What it never does is register a scope-disposal hook. There is no onScopeDispose and no onUnmounted anywhere in the source. Unmount the component mid-request and the fetch runs to completion, which is precisely the third cost from the top of this article. The hand-rolled onCleanup version handles it, because the watcher's cleanup runs when the scope stops. Closing it takes one line, because the wrapper hands back the abort it never calls:

import { onScopeDispose } from 'vue'

const { data, abort } = useFetch(url, { refetch: true }).json()
onScopeDispose(abort) // the half `refetch` doesn't cover: abort the in-flight request when the scope stops

One consequence before wiring it: the abort rejects the request, so onFetchError fires with an AbortError on every unmount that interrupts a fetch. Gate that handler on error.name !== 'AbortError' if it shows a toast or reports to Sentry. None of this is a reason to avoid the library. It's a reason to know which half of the lifecycle you delegated.

TanStack Query (via @tanstack/vue-query) argues the same position from the other end: it hands an AbortSignal to every query function and treats that signal as the universal cancellation contract. The catch is the default. TanStack does not cancel on change or unmount unless the query function actually forwards the signal it's handed (TanStack Query cancellation):

import { useQuery } from '@tanstack/vue-query'

useQuery({
  queryKey: ['search', searchTerm],
  queryFn: ({ signal }) => fetch(`/api/search?q=${searchTerm.value}`, { signal }).then(r => r.json()), // forward `signal` or nothing cancels
})

So "the library makes it automatic" is half true: automatic that the signal exists, manual that it's used. That's the seam in the counter. The primitive's defenders concede the search box to the library — when the app already depends on one, or when the use case wants the cache, dedup, and retry machinery, reaching for TanStack is the right call. What useFetch buys for this problem is the abort bookkeeping, and there's no cache machinery behind it. The line holds where the alternative is adding a data-fetching dependency to abort a single fetch, or where the code needs control the wrapper doesn't expose: the watcher's flush timing, a non-fetch cancellable, cleanup sequenced against other effects. The primitive is small. Owning it is not the sin the counter implies, provided the registration lands where it fires.

The decision rule

Every choice above reduces to one question: is the controller.abort() registration still running inside the watcher's synchronous phase? If yes, any path works — pick on ergonomics. Once the registration has crossed an await, only the bound parameter survives. Everything else the docs dwell on — flush timing, the failSilently flag — the rule dismisses as secondary.

Best practice:

In general: AbortController is the canceller; the only real decision is where the abort() registration runs — and it has to run before the first await, or use the path that doesn't care.

Synchronous registration (no await before it) — reach for onWatcherCleanup; it's the cleanest call and threads no parameter.

Avoid:

  // pre-3.5 plumbing: a separate ref you abort and re-create by hand
  const controller = ref()
  watch(id, () => {
    controller.value?.abort()
    controller.value = new AbortController()
    fetch(`/api/user/${id.value}`, { signal: controller.value.signal })
  })

Prefer:

  watch(id, () => {
    const controller = new AbortController()
    onWatcherCleanup(() => controller.abort()) // co-located, sync phase
    fetch(`/api/user/${id.value}`, { signal: controller.signal })
  })

Async callback — the onCleanup parameter, registered before the first await. An await is in the picture, so the onCleanup parameter is the default over onWatcherCleanup: bound to the watcher instance, it can't be silently stranded when a registration drifts past the await the way the global is. That robustness is separate from the fix. The fix is position: the two snippets below run the identical parameter and signature, and only the registration line moves. Register it above the fetch and the abort is armed while the request is in flight. Drop it below, and the parameter still registers (surviving the await is what it's for), but too late — the fetch has already resolved, and an abort on a settled controller cancels nothing.

Avoid:

  watch(id, async (v, _prev, onCleanup) => {
    const controller = new AbortController()
    await fetch(url, { signal: controller.signal })
    onCleanup(() => controller.abort()) // registers fine — but the fetch already resolved, so there's nothing left to abort
  })

Prefer:

  watch(id, async (v, _prev, onCleanup) => {
    const controller = new AbortController()
    onCleanup(() => controller.abort()) // registered before the await, so the next change can abort this fetch mid-flight
    await fetch(url, { signal: controller.signal })
  })

No appetite to own the registry — reach for a library; useFetch({ refetch: true }), or a TanStack query that forwards signal, hides the AbortController bookkeeping for you. They don't cover the same ground: TanStack aborts when the query goes inactive, useFetch only at the start of the next request.

Prefer:

  const { data, abort } = useFetch(url, { refetch: true }).json()
  onScopeDispose(abort) // abort-on-change is built in; abort-on-unmount is not

The three cases are three distinct fixes: co-locate in synchronous code, thread the parameter across async, or delegate the whole registry to a library that speaks AbortSignal.

The four names collapse to two ways into one registry, plus the object that does the aborting; the registry cares about one thing only: whether the registration call ran while the watcher was still executing synchronously. onWatcherCleanup reads that state from a module variable that's already been cleared by the time an awaited fetch resolves; the onCleanup parameter carries its watcher with it and never has to look. Reach for the global in synchronous code, and the parameter the instant an await enters the picture. The bug was never the request that wouldn't cancel. It was the cleanup registered to a watcher that had already left the room.

Sources

Nuxt docs — useAsyncData — the useAsyncData composable the pre-3.5 Nuxt cancel recipe wraps with an AbortController signal.
TanStack Query — Query Cancellation — AbortSignal-as-contract design and the opt-in default (no cancel unless the signal is forwarded).
Vue 3.5 release announcement (Vue team, September 2024) — introduction of onWatcherCleanup as a globally imported API.
Vue core source — packages/reactivity/src/watch.ts — cleanupMap, activeWatcher, the onWatcherCleanup signature, and the no-active-watcher warning.
Vue docs — Reactivity API: Core — watchEffect / onWatcherCleanup signatures and the synchronous-execution constraint.
Vue docs — Watchers guide — the stale-request rationale and the onCleanup-parameter instance-binding note.
vuejs/docs #3222 — onWatcherCleanup in async contexts — open issue documenting the after-await footgun.
VueUse — useFetch — the abort / canAbort / aborted surface, the timeout cancellation option, and the documented option list, which has no cache or dedup entry.
VueUse — useFetch source — execute() calls abort() before each run (the auto-cancel on URL change), the absence of any module-level cache or in-flight registry, and the absence of any scope-disposal hook.
Axios — Cancellation — CancelToken deprecated in favor of AbortController (added in v0.22.0, October 2021).

DEV Community: Eve

Vue 3 Cleans Up After Itself — Until It Can't

Vue already cleans up the part everyone worries about

Where the leaks actually live

Manual browser resources: timers, listeners, subscriptions, observers

The two watcher leaks

Handles and references that outlive the component

Composables: give the effects a scope to die with

The counter: "Vue cleans up, and VueUse handles the rest"

Detection: confirm the leak before you chase it

What looks like a leak but isn't

What to actually do

Sources

Cancelling API Requests in Vue 3: One Registry, Two Paths, and the Question That Orders Them

The three costs of a request nobody cancelled

The patterns that lost to AbortController

Four names, two registration paths, one registry

The cleanup registry, keyed by the effect

onWatcherCleanup stops working after the first await

Where a library earns the dependency

The decision rule

Sources

The patterns that lost to `AbortController`

`onWatcherCleanup` stops working after the first `await`