WatchEffect & Flush Timing

## What `watchEffect()` is `watchEffect(fn, options?)` is Vue 3's auto-tracking watcher. You do not tell it what to watch; it **finds out by running** `fn` and recording which reactive values `fn` reads. It is imported from `vue` and returns a handle for stopping it. ## When it runs - **First run:** with the default `flush: 'pre'`, `fn` runs **synchronously**, during the `watchEffect()` call itself. There is no `immediate` option because running at once is the default. (A watcher created with `flush: 'post'` is the exception: its first run waits for the post-render queue.) - **Later runs:** when a dependency changes, the effect is not run on the spot. It is **scheduled**, deduplicated, and run in a batch - with the default flush, after parent component updates and before the owner component's DOM update. - **End:** a watcher created synchronously in a component's setup is stopped when the component unmounts. ## What it tracks While `fn` runs, every **reactive read** registers a dependency: - `count.value` on a ref; - `state.filter` on a `reactive()` object, including nested properties you actually touch; - `total.value` on a `computed`; - `props.size` on the props object. Plain variables, non-reactive objects, and values read with reactivity bypassed are not tracked. ## Dependencies are rebuilt every run Vue re-collects the dependency set on **every** run and drops the ones that were not read this time: ```ts watchEffect(() => { if (enabled.value) { draw(points.value) } }) ``` 1. First run with `enabled` false: only `enabled` is read, so only `enabled` is a dependency. Changing `points` does nothing. 2. `enabled` becomes true: the effect re-runs, reads `points`, and now depends on both. 3. `enabled` goes back to false: the next run does not read `points`, so that dependency is dropped again. This is correct behaviour - when the branch is off, `points` cannot affect the result - but it surprises people who expect a fixed list. ## Compared with `watch()` | | `watchEffect(fn)` | `watch(source, cb)` | |---|---|---| | Dependencies | whatever `fn` reads | only the declared source | | First run | immediately (default flush) | lazy unless `immediate: true` | | Callback arguments | none besides the cleanup registrar | new value, old value, cleanup registrar | | Fires when | any tracked read changes | the source value changed | | Nested data | tracks only properties read | needs `deep` to see nested changes | The Vue guide points out that for nested data `watchEffect()` can be **more efficient than a deep watcher**, because it tracks only the properties used rather than traversing everything. ## Reads that are easy to misjudge - **Length versus items.** `items.value.length` tracks the length only; setting `items.value[0].done = true` does not change the length, so the effect does not re-run. - **Serialising tracks everything.** `JSON.stringify(state)` reads every nested property, so the effect now depends on the whole structure - convenient, but as broad as a deep watch. - **Deferred callbacks.** A read inside a `setTimeout` or event-listener callback created by the effect runs later, outside the effect, and is not tracked. - **Raw objects.** Reading through `toRaw(state)` or a plain copy bypasses the proxy, so nothing is registered. The test is always the same: was the value read **through a ref or reactive proxy, during the synchronous run**? ## Practical guidance - Use `watchEffect()` when the side effect naturally reads its own inputs - syncing several values to a chart, a document title, a storage key. - Use `watch()` when you need the old value, laziness, or precise control over which change fires the callback. - Keep reads **synchronous**: only reads made before the first `await` count, so async effects need care. - Do not write to a value you also read and expect a loop; a running effect is not re-triggered by its own writes, which can hide the intent. Derive values with `computed` instead.