Unverified Commit bbec4fe2 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

docs: clarify client cache freshness after hydration (#97180)

## Summary

- add an explicit `staleTime` to the server-seeded TanStack Query
example so hydration does not immediately refetch
- explain when stale TanStack Query data becomes eligible to refetch
- clarify that SWR fallback data revalidates after hydration by default
and that `revalidateIfStale: false` is not a timed freshness window

## Verification

- `prettier --write
docs/01-app/02-guides/client-side-data-fetching/{swr,tanstack-query}.mdx`
- `alex
docs/01-app/02-guides/client-side-data-fetching/{swr,tanstack-query}.mdx
--quiet`
- Not run: full `pnpm lint` (docs-only change; targeted formatting and
language checks passed)

<!-- NEXT_JS_LLM -->
parent 5942b37a
......@@ -245,7 +245,11 @@ export function ProductView({ id }) {
> **Good to know:** The `fallback` key and the `useSWR` key must match exactly. If they drift, SWR ignores the fallback value and fetches on the client.
The `fallback` provides the hook's initial value. After hydration, SWR can revalidate or mutate the same key in its browser cache.
The `fallback` provides the hook's initial value. By default, SWR treats fallback data as stale and starts a browser revalidation after hydration.
SWR does not provide a time-based freshness window for fallback data. Setting `revalidateIfStale: false` skips revalidation when the hook mounts with cached data. This setting applies to every mount, unlike TanStack Query's `staleTime`.
Focus, reconnect, polling, and `mutate` can still revalidate the key. To refresh on a schedule, set [`refreshInterval`](https://swr.vercel.app/docs/revalidation#revalidate-on-interval).
The SWR key points to a [Route Handler](/docs/app/api-reference/file-conventions/route) with a `GET` method. The Route Handler can call the same `getProduct` function that provides the fallback, while the browser uses the URL for revalidation and polling.
......
......@@ -270,6 +270,7 @@ export const productCache = {
if (!res.ok) throw new Error('Failed to fetch product')
return res.json()
},
staleTime: 30_000,
}),
}
```
......@@ -287,11 +288,14 @@ export const productCache = {
if (!res.ok) throw new Error('Failed to fetch product')
return res.json()
},
staleTime: 30_000,
}),
}
```
The query function fetches a [Route Handler](/docs/app/api-reference/file-conventions/route) so it can run on the client. Larger features can place query options in a separate client-facing module as long as every caller imports the key from the same cache contract.
The query function fetches a [Route Handler](/docs/app/api-reference/file-conventions/route) so it can run on the client. The `staleTime` prevents an immediate client refetch by keeping the hydrated data fresh for 30 seconds. Choose a duration based on how quickly the data can change.
Larger features can place query options in a separate client-facing module as long as every caller imports the key from the same cache contract. Learn more about [TanStack Query defaults](https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults).
As with SWR, `params.then()` resolves the `id` inside `<Suspense>`, and `ProductData` prefetches below the boundary.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment