Nuxt 4 Migration: useAsyncData Data Is a shallowRef Now
The ticket was short: pending review count says 4, database says 3, only happens if you sit on the page. I closed it as a caching issue, which is what you write when you have not looked yet. It came back twice in one week, and both reporters had recently pulled the Nuxt 4 migration branch.
That dashboard does nothing clever. It loads its numbers with useAsyncData, and when someone approves a review it posts, then patches the local copy so the UI does not wait for a refetch.
const { data: stats } = await useAsyncData('dashboard-stats', () => $fetch('/api/stats'))
async function approve(id) {
await $fetch(`/api/reviews/${id}/approve`, { method: 'POST' })
stats.value.pending -= 1
stats.value.recent.unshift({ id, state: 'approved' })
}
On Nuxt 3 that worked. On Nuxt 4 the badge sat there until I navigated away and back, which made the fetch look stale. It was not. The fetch was fine. The component simply never re-rendered.
Here is the line that explains it, from node_modules/nuxt/dist/app/composables/asyncData.js:
const _ref = options.deep ? ref : shallowRef;
// a few lines further down
data: _ref(hasCachedData ? initialCachedData : options.default()),
The option's own comment in asyncData.d.ts says deep is false by default. So data is a plain shallowRef now, which means tracking stops one level in. Assigning stats.value is a signal. Changing stats.value.pending is not, because that object was never wrapped in a proxy.
Measured, not guessed
I did not want to trust my own reading of a bundled file, so I ran the smallest probe I could against the Vue build in this project. One effect reading two nested fields, three nested mutations, one replacement:
import { shallowRef, ref, isShallow, isReactive, effect } from 'vue'
function probe(label, makeRef) {
const data = makeRef({ rows: [{ id: 1 }] })
let runs = 0
effect(() => { runs++; data.value.rows.length + (data.value.rows[0]?.id ?? 0) })
data.value.rows.push({ id: 2 }) // nested push
data.value.rows[0].id = 99 // nested set
data.value.rows.sort((a, b) => b.id - a.id) // nested reorder
data.value = { rows: [{ id: 5 }] } // replacement
console.log(label, isShallow(data), isReactive(data.value), runs)
}
probe('shallow', shallowRef) // true false 2
probe('deep', ref) // false true 4
Two runs for the shallow ref: the initial one and the replacement. All three nested mutations went past it unseen. The deep ref caught the push and the nested set as well, and stayed quiet on the sort only because that array happened to be in order already.
Why it reads like a caching bug
Nothing got frozen or copied. The object is still live, so the next time the component renders for any reason at all (a route change, a hover state, a parent update), the template reads the mutated object and the right number is there.
That self-healing is what sends people hunting in the wrong place. A normal bug stays broken. This one is wrong only until something unrelated forces a render, so the suspects become the API, the payload, and getCachedData, and all three are innocent.
Three fixes, and the one I picked
Cheapest is to stop mutating in place. Build a new object and assign it:
// silent under shallowRef
stats.value.pending -= 1
// visible
stats.value = { ...stats.value, pending: stats.value.pending - 1 }
Second is opting back into deep reactivity for that one call, useAsyncData('dashboard-stats', handler, { deep: true }). Third is keeping the shallow ref and holding the parts you mutate in a separate ref, which is what I did for the recent list since it also gets locally re-sorted.
I went with replacement plus one local ref and left deep: true out. Deep is what we had before, and honestly I liked it. Nuxt changed that default for a reason though: a deep ref turns every object in the response into a proxy the first time something touches it, and most of a stats payload never reaches the DOM. I am not going to undo a deliberate performance default to save three lines of assignment. Shallow is the better call. It is just a call that fails quietly, and quiet failures eat more afternoons than loud ones.
Traps that ride along
Before you sprinkle deep: true around, know that entries are keyed and buildAsyncData only runs for the first call on a key. A second component calling useAsyncData('dashboard-stats', handler, { deep: true }) gets handed the existing shallow ref, plus a dev warning about a mismatching deep option. The first caller decides, not the one asking for deep.
The shared key also means shared data, error and status, so a second call with its own transform or default will disagree with the first. And dedupe no longer takes a boolean. It is 'cancel' or 'defer', defaulting to 'cancel'.
One more, from the same upgrade and unrelated to reactivity: the initial value is undefined now. getDefault in that file is literally () => void 0, and error is a toRef into an errors object that also starts empty. Every === null check around fetched data stops matching. I found four in our codebase, all inside empty-state branches that had been dead for a fortnight without anyone noticing.
What I run before the next upgrade
Greps. Cheap and boring:
# nested mutation on fetched data
grep -rnE "data\.value\.[A-Za-z0-9_]+\.(push|splice|sort|reverse|shift|unshift)\(" \
--include=*.vue --include=*.ts app/
grep -rnE "data\.value\.[A-Za-z0-9_]+\s*[-+*/]?=[^=]" \
--include=*.vue --include=*.ts app/
# null checks that are now dead
grep -rnE "(data|error)\.value\s*[!=]==?\s*null" --include=*.vue --include=*.ts app/
That is the whole audit. Three greps and a read of every hit, which for us was nineteen hits and six real problems. I keep them in Snippet Ark tagged per repo, because I have retyped that last regex from memory twice and botched it both times.
If you are still on Nuxt 3, the useFetch vs $fetch trap is the right thing to read before this one, since shallow data changes what "the data is already there" actually buys you. And if your migration produced duplicated state between users instead of stale numbers, that is a different bug with a similar smell.
The upgrade itself was fine. Nuxt 4 has been solid for us since the first week and I would make the same call again. But this default deserved a louder line in the release notes than it got, because it breaks no build, fails no test, and shows up only as a number that is quietly one behind.