data-fetching-caching/caching

83 notes in this subject, read out of this brain and free to use. This is page 2 of 2.

fetchCache parent-child constraints

A parent cannot provide 'default-no-store' if a child provides 'auto' or '*-cache' since that could make the same fetch have different behavior. It is generally recommended to leave shared parent layouts as 'auto'.

next.revalidate option for time-based revalidation

Use the next.revalidate option on fetch to revalidate data after a specified number of seconds. Example: fetch('https://...', { next: { revalidate: 3600 } }).

revalidate route segment config

The revalidate export sets the default revalidation time for a layout or page. Valid values are: false (default, cache indefinitely), 0 (always dynamically render), or a number in seconds (set revalidation frequency).

revalidate false behavior

When revalidate is false (default), it caches any fetch requests that set cache to 'force-cache' or are discovered before a Request-time API is used. Individual fetch requests can still use cache: 'no-store' or revalidate: 0 to avoid being cached.

revalidate 0 behavior

When revalidate is 0, it ensures a layout or page is always dynamically rendered even if no Request-time APIs are discovered. It changes the default of fetch requests without a cache option to 'no-store' but leaves fetch requests that opt into 'force-cache' or use positive revalidate unchanged.

revalidate value must be statically analyzable

The revalidate value needs to be statically analyzable. For example, revalidate = 600 is valid, but revalidate = 60 * 10 is not.

revalidate frequency determined by lowest value

The lowest revalidate across each layout and page of a single route determines the revalidation frequency of the entire route. This ensures child pages are revalidated as frequently as their parent layouts.

individual fetch revalidate can increase frequency

Individual fetch requests can set a lower revalidate than the route's default revalidate to increase the revalidation frequency of the entire route.

pages always rendered on-demand in development

In Development, Pages are always rendered on-demand and are never cached. This allows developers to see changes immediately without waiting for a revalidation period to pass.

revalidateTag for on-demand cache invalidation

Use revalidateTag() from 'next/cache' to invalidate cached data by tag. This is used in Server Actions or Route Handlers to revalidate cached fetch requests tagged with next.tags.

revalidatePath for on-demand cache invalidation

Use revalidatePath() from 'next/cache' to invalidate all cached data for a specific route path. This is used in Server Actions or Route Handlers.

next.tags option enables on-demand revalidation

Tag fetch requests with next.tags to enable on-demand cache invalidation. Example: fetch('https://...', { next: { tags: ['user'] } }). Tags can then be invalidated using revalidateTag().

React cache function deduplicates requests

If not using fetch (which is automatically memoized), wrap data access with the React cache function to deduplicate requests within a single render pass. This is useful for ORMs or direct database access.

Preloading data with React cache and server-only

Combine the server-only package with React's cache to create a reusable preload utility. Call preload() before blocking requests to initiate data fetching early so data is already available when the component renders.

Preload utility example

Create a preload utility with cache and server-only: export const getItem = cache(async (id: string) => { ... }); export const preload = (id: string) => { void getItem(id) }. Then call preload(id) before blocking work.

Preloading in page component

Call preload() in the page component before any blocking asynchronous tasks to start loading data immediately. The data will be available when child components call the cached function.

Previous model caching guide applies without Cache Components

This guide applies to projects not using Cache Components which was introduced in version 16 under the cacheComponents flag. Projects using Cache Components should use different caching approaches.

Three cache layers can hold related data when both server and client caching are enabled

When both initial data provision and server caching are enabled, three cache layers can hold related data. Next.js server cache stores cached data and Server Component output, controlled with `cacheLife` `revalidate` and `expire`. Next.js client cache stores React Server Component payloads for visited and prefetched routes, controlled with `cacheLife` `stale`. Client data-fetching library stores browser data under an SWR key or TanStack query key, controlled by the library's revalidation options and mutations.

Cache layers keep independent freshness policies and do not require matching durations

The three cache layers (Next.js server cache, Next.js client cache, and client data-fetching library cache) keep independent freshness policies and do not need matching durations. However, cache identities and mutation invalidation must stay coordinated across layers.

Next.js prefetching places React Server Component payload in client cache before navigation

Next.js prefetching can place a route's React Server Component payload in the client cache before navigation occurs.

Cache server-provided SWR fallback with Cache Components

Enable cacheComponents in next.config.ts to cache the server data used as the SWR fallback. Add 'use cache' directive, choose a cacheLife profile, and apply cacheTag so mutations can invalidate it. This example caches a product fetch with cacheLife('max') because writes invalidate the product tag.

cacheLife stale vs revalidate vs expire

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. Choose a shorter profile when the server value should refresh with time.

Shared cache contract for SWR key and server tag

When the same mutation updates the browser cache and invalidates cached server data, define both SWR key and server tag identities in one shared contract object. Keep this contract free of server-only and client-only imports so both cache layers can reuse it.

Give your agent this brain