new·The score now tells you which way it movedA brain's exam only ever grows: its own material writes questions, and so does every question a real caller asked and did not get answered. The score is a percentage over that growing set, so a brain that learned more could post a smaller number — and this week three did. One of them answered two MORE questions than the week before and showed eighteen points less. Printed as a single percentage, that reads as decline to a reader and as punishment to anyone who contributes material.all news →
mozg.beta
Sign in

Next.js · Guides · all subjects

caching/cdn

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

Cache-Control headers for static pages

Next.js sets `s-maxage=31536000` (one year) for static pages with no revalidation.

Cache-Control headers for ISR pages

Next.js sets `s-maxage={revalidate}, stale-while-revalidate={expire - revalidate}` for ISR pages with time-based revalidation. The default expire is one year, so stale-while-revalidate is included by default. This can be customized with cacheLife.

Cache-Control headers for dynamic pages

Next.js sets `private, no-cache, no-store, max-age=0, must-revalidate` for dynamic pages that should not be cached.

Static assets cache headers

Static assets served from /_next/static/ include content hashes in filenames and have `public, max-age=31536000, immutable` directives, representing a 1 year max-age.

On-demand revalidation does not propagate to CDN automatically

CDN-level caching does not support on-demand revalidation. Calls to revalidateTag() or revalidatePath() invalidate the Next.js server cache, but the CDN continues serving its cached copy until the s-maxage TTL expires. To propagate on-demand revalidation to the CDN, you must trigger CDN purges alongside your revalidation call. A common pattern is to call revalidateTag()/revalidatePath() to invalidate the Next.js server cache, then call your CDN purge API for the affected keys including both HTML and RSC variants.

Vary header signals cache variability to CDNs

Next.js sets a Vary header on responses to signal CDN cache variability based on custom request headers: rsc (whether to return RSC payload instead of HTML), next-router-state-tree (client's current router state for targeted segment updates), next-router-prefetch (whether this is a prefetch request), next-router-segment-prefetch (specific segment being prefetched), and next-url (for interception routes, carries the URL being intercepted).

_rsc search parameter as cache-key discriminator

Next.js uses the _rsc search parameter as a hash of relevant request header values that acts as a cache-key to ensure different response variants get different cache keys. This ensures correct responses even on CDNs that ignore Vary headers.

PPR-enabled routes require _rsc in cache key

For PPR-enabled routes, when the next-router-prefetch header is set, a CDN can cache the static prefetch response if it includes the _rsc search parameter in the cache key to distinguish prefetch variants from HTML responses, and respects the Cache-Control headers Next.js sets.

Proxy.js should run before CDN cache

Proxy.js (previously Middleware) should run before the CDN cache so it remains the source of truth for auth, redirects, and rewrites. If deployment places proxy.js behind the CDN, configure the cache layer to bypass caching for routes that depend on proxy.js decisions.

next-router-state-tree header can be safely omitted in specific cases

The next-router-state-tree header can be omitted on non-prefetch RSC requests without causing protocol errors. The server returns a full payload instead of a targeted segment update, but the response is still parseable and the server still returns the correct data.

next-router-segment-prefetch header can be safely omitted

The next-router-segment-prefetch header can be omitted on prefetch requests without causing protocol errors. The server falls back to a broader prefetch payload instead of a segment-specific one.

next-url header can be omitted but breaks interception routes

The next-url header is used for interception routes to vary the response based on the referring page. If omitted, interception routes are not supported and the server doesn't know what original path to match against. The response returned is for regular navigation when next-url is omitted: the user sees the target page instead of the intercepted target page.

rsc header must be preserved by CDN

The rsc header must be forwarded from the client to the server. This header tells the server to return an RSC payload instead of HTML. If a CDN strips it, the server returns HTML when the client-side router expects RSC data, which breaks client-side navigation and causes browser navigations instead. The Vary header and _rsc parameter exist specifically to prevent CDNs from serving a cached HTML response to an RSC request or vice versa.

next-router-prefetch header and _rsc parameter must be preserved together

When next-router-prefetch is present, both the prefetch header and the _rsc search parameter must be preserved. For prefetch flows, _rsc is a required cache-busting discriminator and should be treated as mandatory.

_rsc search parameter must be in cache key

The _rsc search parameter must be included in the CDN cache key as it distinguishes response variants (HTML vs. RSC, different prefetch types). Ensure your CDN does not strip query parameters from cache keys, as some CDNs do this by default.

307 redirect for incorrect _rsc value

By default, when an RSC request arrives without the correct _rsc value, the server responds with a 307 redirect to the URL with the correct hash. This behavior can be disabled by setting experimental.validateRSCRequestHeaders to false. CDNs should follow this redirect. Platforms that compute the hash upstream can rewrite requests to include the correct _rsc before forwarding to avoid an extra round trip.

Pathname-based cache keying direction for Next.js CDN caching

The Next.js team is working on moving all cache-affecting inputs into the URL pathname, eliminating the need for Vary on custom headers and removing the _rsc search parameter. This new approach would use file extensions in the pathname to identify response type: /my/page.rsc returns the RSC payload for the entire page, and /my/page.segments/path/to/segment.segment.rsc returns the RSC payload for a specific segment.

Pathname-based caching allows search parameters to be dropped

Under the pathname-based cache keying approach, search parameters can be safely dropped without affecting returned responses because the pathname determines the cache key and anything in the pathname affects which response variant is returned.

Interception routes under pathname-based caching

Under the pathname-based cache keying scheme, interception variability would be encoded in a search parameter rather than the pathname. If a CDN preserves search params, interception works correctly. If a CDN drops search params, interception is not supported and would gracefully degrade to the non-intercepted page without breaking client-side navigations. This makes interception route support an opt-in CDN capability rather than a requirement.

assetPrefix for custom asset domain or CDN origin

You can use assetPrefix to serve static assets from a different domain or CDN origin.

Cache Components enable pathname-based segment prefetches

When Cache Components is enabled, segment-level prefetches use pathname-based routes (for example, /page.segments/_tree.segment.rsc), and CDNs can cache these with standard pathname-based cache keys.

CDN must respect Vary header and Cache-Control directives

If a CDN caches Next.js responses, it should respect the Vary header and the Cache-Control directives that Next.js sets. Do not cache HTML and RSC payload responses separately with different TTLs.

Give your agent this brain