In Vue 3, how does onWatcherCleanup() differ from the onCleanup argument a watcher receives, and why can onWatcherCleanup fail inside an async callback?

## Two ways to register the same thing A Vue watcher can register **cleanup functions** that Vue calls: - right **before the watcher runs again** - for `watch`, before the callback is invoked with a new value; for `watchEffect`, before the effect function re-runs; - when the watcher is **stopped** - through its handle, or automatically when its owning component unmounts. There are two APIs for registering them, and they differ in how they find the watcher. ## The `onCleanup` argument `onCleanup` is handed to your function by Vue: ```ts watch(id, (newId, oldId, onCleanup) => { const timer = setInterval(poll, 1000, newId) onCleanup(() => clearInterval(timer)) }) watchEffect((onCleanup) => { const off = subscribe(channel.value) onCleanup(off) }) ``` - It is the **third** parameter of a `watch` callback and the **first** parameter of a `watchEffect` function. - It has existed throughout Vue 3. - It is **bound to its watcher** when the watcher is created. Calling it later - after an `await`, in a `.then()` - still registers the cleanup on the right watcher. The docs state this explicitly: the argument form is not subject to the synchronous constraint. ## `onWatcherCleanup()` ```ts import { watch, onWatcherCleanup } from 'vue' watch(id, (newId) => { const controller = new AbortController() onWatcherCleanup(() => controller.abort()) load(newId, controller.signal) }) ``` - It is **imported** from `vue` and was added in **Vue 3.5**. - It has no watcher parameter. It attaches the cleanup to the **currently active watcher** - an internal variable Vue sets just before calling your callback or effect function and restores right after the synchronous call returns. - Therefore it only works during the **synchronous execution** of the callback. ## Why it fails after an `await` An `async` function runs synchronously up to its first `await`, then returns a promise. Vue's call to your callback has already returned at that point, and Vue has restored the active watcher to whatever it was before - normally nothing. When the rest of the function resumes in a microtask: 1. `onWatcherCleanup(fn)` looks up the active watcher; 2. finds none; 3. in development, logs `onWatcherCleanup() was called when there was no active watcher to associate with.`; 4. does **not** register `fn`. In a production build the warning is gone and the cleanup is silently lost - a timer keeps ticking, a subscription keeps delivering. ```ts watch(id, async (newId) => { const data = await load(newId) onWatcherCleanup(() => {}) // too late: warns in dev, never registered }) ``` ## Choosing between them | | `onCleanup` argument | `onWatcherCleanup()` | |---|---|---| | Availability | all of Vue 3 | 3.5+ | | Obtained by | callback parameter | import from `vue` | | Called after an `await` | registers on its own watcher | not registered; dev warning | | Called from a helper | the helper must receive the argument | works if the helper runs synchronously inside the run | | Works in `watchEffect` | yes, first argument | yes | Practical guidance: - In 3.5 code, `onWatcherCleanup()` reads cleanly and lets a small helper (for example one that starts a subscription) register its own cleanup, as long as it is called synchronously. - If cleanup must be registered after asynchronous work, use the **argument** - but ask first whether it should have been registered earlier. A cleanup registered late cannot cancel what happened while the run was awaiting. - Keep one convention per codebase so reviewers know where to look for the teardown. ## Why Vue added the imported form The argument form works, but it couples every piece of teardown to the callback's signature. A watcher that starts a subscription, a timer and a request through three small helpers has to pass `onCleanup` into each of them. With `onWatcherCleanup()`, each helper registers its own teardown next to the resource it creates, which keeps the code that acquires a resource and the code that releases it side by side. The price is the synchronous-only rule, which is invisible in the helper's signature - so a helper that registers cleanup should say so in its name or documentation. ## A common misreading "Must be called synchronously" does not mean the callback must be synchronous. An `async` callback is fine; only the **registration** has to happen before the first `await`. Create the controller or the subscription, register its cleanup, then await.