configuration: cache

10 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Three cache layers for server data with Cache Components

When both providing initial data and caching it on the server are enabled, three cache layers can hold related data: (1) Next.js server cache storing cached data and Server Component output, freshness controlled by cacheLife revalidate and expire; (2) Next.js client cache storing React Server Component payloads for visited and prefetched routes, freshness controlled by cacheLife stale; (3) Client data-fetching library storing browser data under an SWR key or TanStack query key, freshness controlled by the library's revalidation options and mutations.

Cache layers have independent freshness policies

The cache layers keep independent freshness policies and do not need matching durations. Cache identities and mutation invalidation must stay coordinated across layers.

cacheLife profile for SWR fallback data

Use cacheLife('max') when writes invalidate a cache tag. Within the cache profile, stale controls how long the Next.js client cache can reuse a prefetched payload, while revalidate and expire control the server cache.

cacheLife profile duration controls for stale and revalidate

Within a cacheLife profile, stale controls how long the Next.js client cache can reuse a prefetched payload, while revalidate and expire control the server cache. TanStack Query owns a separate browser cache, so its staleTime does not need to match cacheLife.

Client Component prerendering with Suspense and current time

When Cache Components are enabled, Next.js prerenders Client Components. Keep queries needed during the initial render behind Suspense. TanStack Query reads the current time while creating active query state, and the Suspense boundary lets Next.js defer that work instead of raising a current-time prerender error.

dehydrate() reads current time during Cache Components prerendering

TanStack Query's dehydrate() reads the current time (Date.now()) during Cache Components prerendering, which causes a current-time prerender error. Use a prerenderable hydration helper that wraps the timestamp read in 'use cache' with the same tags as the data reads instead.

Prerenderable hydration helper with cached timestamp

Create a helper function that wraps getHydrationUpdatedAt in 'use cache' with cacheTag and cacheLife('max'), returning Date.now(). Pass data and tag array to a dehydrate function that calls the timestamp helper, then manually builds the DehydratedState by calling queryClient.setQueryData with the updatedAt timestamp.

Hydration timestamp advances with cached data on mutation

When a mutation invalidates tags, both the data and its cached timestamp advance together. This ensures HydrationBoundary overwrites the client query on the next navigation with fresh hydration state.

revalidatePath function for cache revalidation

After performing a mutation, call revalidatePath from next/cache within the Server Function to revalidate the Next.js cache and show updated data.

revalidateTag function for tagged cache revalidation

After performing a mutation, call revalidateTag from next/cache within the Server Function to revalidate tagged cached data and show updated data.

Give your agent this brain