fix(nuxt): use single synced asyncdata instance per key (#31373)

Author: danielroe

docs/1.getting-started/10.data-fetching.md

@@ -56,7 +56,7 @@ In the example above, `useFetch` would make sure that the request would occur in
 
 ### Suspense
 
-Nuxt uses Vue’s [`<Suspense>`](https://vuejs.org/guide/built-ins/suspense) component under the hood to prevent navigation before every async data is available to the view. The data fetching composables can help you leverage this feature and use what suits best on a per-call basis.
+Nuxt uses Vue's [`<Suspense>`](https://vuejs.org/guide/built-ins/suspense) component under the hood to prevent navigation before every async data is available to the view. The data fetching composables can help you leverage this feature and use what suits best on a per-call basis.
 
 ::note
 You can add the [`<NuxtLoadingIndicator>`](/docs/api/components/nuxt-loading-indicator) to add a progress bar between page navigations.
@@ -250,7 +250,7 @@ If you have not fetched data on the server (for example, with `server: false`),
 
 ### Lazy
 
-By default, data fetching composables will wait for the resolution of their asynchronous function before navigating to a new page by using Vue’s Suspense. This feature can be ignored on client-side navigation with the `lazy` option. In that case, you will have to manually handle loading state using the `status` value.
+By default, data fetching composables will wait for the resolution of their asynchronous function before navigating to a new page by using Vue's Suspense. This feature can be ignored on client-side navigation with the `lazy` option. In that case, you will have to manually handle loading state using the `status` value.
 
 ```vue twoslash [app.vue]
 <script setup lang="ts">
@@ -350,14 +350,70 @@ Both `pick` and `transform` don't prevent the unwanted data from being fetched i
 [`useFetch`](/docs/api/composables/use-fetch) and [`useAsyncData`](/docs/api/composables/use-async-data) use keys to prevent refetching the same data.
 
 - [`useFetch`](/docs/api/composables/use-fetch) uses the provided URL as a key. Alternatively, a `key` value can be provided in the `options` object passed as a last argument.
-- [`useAsyncData`](/docs/api/composables/use-async-data) uses its first argument as a key if it is a string. If the first argument is the handler function that performs the query, then a key that is unique to the file name and line number of the instance of `useAsyncData` will be generated for you.
+- [`useAsyncData`](/docs/api/composables/use-async-data) uses its first argument as a key if it is a string. If the first argument is the handler function that performs the query, then a key that is unique to the file name and line number of the instance of `useAsyncData` will be generated for you.
 
 ::tip
 To get the cached data by key, you can use [`useNuxtData`](/docs/api/composables/use-nuxt-data)
 ::
 
 :video-accordion{title="Watch a video from Vue School on caching data with the key option" videoId="1026410044" platform="vimeo"}
 
+#### Shared State and Option Consistency
+
+When multiple components use the same key with `useAsyncData` or `useFetch`, they will share the same `data`, `error` and `status` refs. This ensures consistency across components but requires some options to be consistent.
+
+The following options **must be consistent** across all calls with the same key:
+- `handler` function
+- `deep` option
+- `transform` function
+- `pick` array
+- `getCachedData` function
+- `default` value
+
+```ts
+// ❌ This will trigger a development warning
+const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
+const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })
+```
+
+The following options **can safely differ** without triggering warnings:
+- `server`
+- `lazy`
+- `immediate`
+- `dedupe`
+- `watch`
+
+```ts
+// ✅ This is allowed
+const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: true })
+const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: false })
+```
+
+If you need independent instances, use different keys:
+
+```ts
+// These are completely independent instances
+const { data: users1 } = useAsyncData('users-1', () => $fetch('/api/users'))
+const { data: users2 } = useAsyncData('users-2', () => $fetch('/api/users'))
+```
+
+#### Reactive Keys
+
+You can use computed refs, plain refs or getter functions as keys, allowing for dynamic data fetching that automatically updates when dependencies change:
+
+```ts
+// Using a computed property as a key
+const userId = ref('123')
+const { data: user } = useAsyncData(
+  computed(() => `user-${userId.value}`),
+  () => fetchUser(userId.value)
+)
+
+// When userId changes, the data will be automatically refetched
+// and the old data will be cleaned up if no other components use it
+userId.value = '456'
+```
+
 #### Refresh and execute
 
 If you want to fetch or refresh data manually, use the `execute` or `refresh` function provided by the composables.

docs/1.getting-started/18.upgrade.md

@@ -225,6 +225,80 @@ export default defineNuxtConfig({
 })
 ```
 
+### Singleton Data Fetching Layer
+
+🚦 **Impact Level**: Moderate
+
+#### What Changed
+
+Nuxt's data fetching system (`useAsyncData` and `useFetch`) has been significantly reorganized for better performance and consistency:
+
+1. **Shared refs for the same key**: All calls to `useAsyncData` or `useFetch` with the same key now share the same `data`, `error` and `status` refs. This means that it is important that all calls with an explicit key must not have conflicting `deep`, `transform`, `pick`, `getCachedData` or `default` options.
+
+2. **More control over `getCachedData`**: The `getCachedData` function is now called every time data is fetched, even if this is caused by a watcher or calling `refreshNuxtData`. (Previously, new data was always fetched and this function was not called in these cases.) To allow more control over when to use cached data and when to refetch, the function now receives a context object with the cause of the request.
+
+3. **Reactive key support**: You can now use computed refs, plain refs or getter functions as keys, which enables automatic data refetching (and stores data separately).
+
+4. **Data cleanup**: When the last component using data fetched with `useAsyncData` is unmounted, Nuxt will remove that data to avoid ever-growing memory usage.
+
+#### Reasons for Change
+
+These changes have been made to improve memory usage and increase consistency with loading states across calls of `useAsyncData`.
+
+#### Migration Steps
+
+1. **Check for inconsistent options**: Review any components using the same key with different options or fetch functions.
+
+   ```ts
+   // This will now trigger a warning
+   const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
+   const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })
+   ```
+
+   It may be beneficial to extract any calls to `useAsyncData` that share an explicit key (and have custom options) into their own composable:
+
+   ```ts [composables/useUserData.ts]
+   export function useUserData(userId: string) {
+     return useAsyncData(
+       `user-${userId}`,
+       () => fetchUser(userId),
+       { 
+         deep: true,
+         transform: (user) => ({ ...user, lastAccessed: new Date() })
+       }
+     )
+   }
+   ```
+
+2. **Update `getCachedData` implementations**:
+
+   ```diff
+   useAsyncData('key', fetchFunction, {
+   -  getCachedData: (key, nuxtApp) => {
+   -    return cachedData[key]
+   -  }
+   +  getCachedData: (key, nuxtApp, ctx) => {
+   +    // ctx.cause - can be 'initial' | 'refresh:hook' | 'refresh:manual' | 'watch'
+   +    
+   +    // Example: Don't use cache on manual refresh
+   +    if (ctx.cause === 'refresh:manual') return undefined
+   +    
+   +    return cachedData[key]
+   +  }
+   })
+   ```
+
+Alternatively, for now, you can disable this behaviour with:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    granularCachedData: false,
+    purgeCachedData: false
+  }
+})
+```
+
 ### Deduplication of Route Metadata
 
 🚦 **Impact Level**: Minimal

docs/2.guide/3.going-further/1.experimental-features.md

@@ -605,3 +605,19 @@ export default defineNuxtConfig({
 ::read-more{icon="i-simple-icons-github" color="gray" to="https://github.com/nuxt/nuxt/pull/31379" target="_blank"}
 See PR #31379 for implementation details.
 ::
+
+## granularCachedData
+
+Whether to call and use the result from `getCachedData` when refreshing data for `useAsyncData` and `useFetch` (whether by `watch`, `refreshNuxtData()`, or a manual `refresh()` call.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    granularCachedData: true
+  }
+})
+```
+
+::read-more{icon="i-simple-icons-github" color="gray" to="https://github.com/nuxt/nuxt/pull/31373" target="_blank"}
+See PR #31373 for implementation details.
+::

docs/3.api/2.composables/use-async-data.md

@@ -53,8 +53,25 @@ const { data: posts } = await useAsyncData(
 </script>
 ```
 
+### Reactive Keys
+
+You can use a computed ref, plain ref or a getter function as the key, allowing for dynamic data fetching that automatically updates when the key changes:
+
+```vue [pages/[id\\].vue]
+<script setup lang="ts">
+const route = useRoute()
+const userId = computed(() => `user-${route.params.id}`)
+
+// When the route changes and userId updates, the data will be automatically refetched
+const { data: user } = useAsyncData(
+  userId,
+  () => fetchUserById(route.params.id)
+)
+</script>
+```
+
 ::warning
-[`useAsyncData`](/docs/api/composables/use-async-data) is a reserved function name transformed by the compiler, so you should not name your own function [`useAsyncData`](/docs/api/composables/use-async-data) .
+[`useAsyncData`](/docs/api/composables/use-async-data) is a reserved function name transformed by the compiler, so you should not name your own function [`useAsyncData`](/docs/api/composables/use-async-data).
 ::
 
 :read-more{to="/docs/getting-started/data-fetching#useasyncdata"}
@@ -74,7 +91,7 @@ The `handler` function should be **side-effect free** to ensure predictable beha
   - `transform`: a function that can be used to alter `handler` function result after resolving
   - `getCachedData`: Provide a function which returns cached data. A `null` or `undefined` return value will trigger a fetch. By default, this is:
     ```ts
-    const getDefaultCachedData = (key, nuxtApp) => nuxtApp.isHydrating 
+    const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating 
       ? nuxtApp.payload.data[key] 
       : nuxtApp.static.data[key]
     ```
@@ -96,6 +113,35 @@ You can use `useLazyAsyncData` to have the same behavior as `lazy: true` with `u
 
 :video-accordion{title="Watch a video from Alexander Lichter about client-side caching with getCachedData" videoId="aQPR0xn-MMk"}
 
+### Shared State and Option Consistency
+
+When using the same key for multiple `useAsyncData` calls, they will share the same `data`, `error` and `status` refs. This ensures consistency across components but requires option consistency.
+
+The following options **must be consistent** across all calls with the same key:
+- `handler` function
+- `deep` option
+- `transform` function
+- `pick` array
+- `getCachedData` function
+- `default` value
+
+The following options **can differ** without triggering warnings:
+- `server`
+- `lazy`
+- `immediate`
+- `dedupe`
+- `watch`
+
+```ts
+// ❌ This will trigger a development warning
+const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
+const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })
+
+// ✅ This is allowed
+const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: true })
+const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: false })
+```
+
 ## Return Values
 
 - `data`: the result of the asynchronous function that is passed in.
@@ -124,7 +170,7 @@ function useAsyncData<DataT, DataE>(
   options?: AsyncDataOptions<DataT>
 ): AsyncData<DataT, DataE>
 function useAsyncData<DataT, DataE>(
-  key: string,
+  key: string | Ref<string> | ComputedRef<string>,
   handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
   options?: AsyncDataOptions<DataT>
 ): Promise<AsyncData<DataT, DataE>>
@@ -138,8 +184,13 @@ type AsyncDataOptions<DataT> = {
   default?: () => DataT | Ref<DataT> | null
   transform?: (input: DataT) => DataT | Promise<DataT>
   pick?: string[]
-  watch?: WatchSource[]
-  getCachedData?: (key: string, nuxtApp: NuxtApp) => DataT | undefined
+  watch?: WatchSource[] | false
+  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
+}
+
+type AsyncDataRequestContext = {
+  /** The reason for this data request */
+  cause: 'initial' | 'refresh:manual' | 'refresh:hook' | 'watch'
 }
 
 type AsyncData<DataT, ErrorT> = {

docs/3.api/2.composables/use-fetch.md

@@ -66,6 +66,22 @@ const { data, status, error, refresh, clear } = await useFetch('/api/auth/login'
 })
 ```
 
+### Reactive Keys and Shared State
+
+You can use a computed ref or a plain ref as the URL, allowing for dynamic data fetching that automatically updates when the URL changes:
+
+```vue [pages/[id\\].vue]
+<script setup lang="ts">
+const route = useRoute()
+const id = computed(() => route.params.id)
+
+// When the route changes and id updates, the data will be automatically refetched
+const { data: post } = await useFetch(() => `/api/posts/${id.value}`)
+</script>
+```
+
+When using `useFetch` with the same URL and options in multiple components, they will share the same `data`, `error` and `status` refs. This ensures consistency across components.
+
 ::warning
 `useFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useFetch`.
 ::
@@ -109,7 +125,7 @@ All fetch options can be given a `computed` or `ref` value. These will be watche
   - `transform`: a function that can be used to alter `handler` function result after resolving
   - `getCachedData`: Provide a function which returns cached data. A `null` or `undefined` return value will trigger a fetch. By default, this is:
     ```ts
-    const getDefaultCachedData = (key, nuxtApp) => nuxtApp.isHydrating 
+    const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating 
       ? nuxtApp.payload.data[key] 
       : nuxtApp.static.data[key]
     ```
@@ -170,7 +186,7 @@ type UseFetchOptions<DataT> = {
   server?: boolean
   lazy?: boolean
   immediate?: boolean
-  getCachedData?: (key: string, nuxtApp: NuxtApp) => DataT | undefined
+  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
   deep?: boolean
   dedupe?: 'cancel' | 'defer'
   default?: () => DataT
@@ -179,6 +195,11 @@ type UseFetchOptions<DataT> = {
   watch?: WatchSource[] | false
 }
 
+type AsyncDataRequestContext = {
+  /** The reason for this data request */
+  cause: 'initial' | 'refresh:manual' | 'refresh:hook' | 'watch'
+}
+
 type AsyncData<DataT, ErrorT> = {
   data: Ref<DataT | null>
   refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>

nuxt.config.ts

@@ -21,6 +21,19 @@ export default defineNuxtConfig({
   dir: {
     app: fileURLToPath(new URL('./test/runtime/app', import.meta.url)),
   },
+  vite: {
+    plugins: [
+      {
+        name: 'enable some dev logging',
+        enforce: 'pre',
+        transform (code) {
+          if (code.includes('import.meta.dev /* and in test */')) {
+            return code.replace('import.meta.dev /* and in test */', 'true')
+          }
+        },
+      },
+    ],
+  },
   typescript: {
     shim: process.env.DOCS_TYPECHECK === 'true',
     hoist: ['@vitejs/plugin-vue', 'vue-router'],