Skip to content

PATTERN Cited by 1 source

Framework-inferred cache policy

Definition

Framework-inferred cache policy is the pattern of having the CDN / edge / cache layer learn per-route cache semantics from the application framework's build output rather than requiring the developer to annotate cacheability on each route explicitly.

The shape:

  1. The application framework (Next.js, SvelteKit, Nuxt, …) has first-class route-type primitives (SSG, ISR, SSR, API, dynamic).
  2. The build step analyses each route and classifies it.
  3. The classification is serialised into metadata shipped with the deployment.
  4. The CDN reads the metadata on each request and applies the correct caching / collapsing / invalidation policy automatically.
  5. The developer never touches CDN configuration directly.

The canonical production instance is Vercel's CDN: when an app is deployed, Vercel analyses the Next.js routes and distributes the per-route cacheability metadata to every CDN region. At request time, the CDN already knows whether a route can be cached and collapsed — without any config from the user.

The asymmetry being exploited

The framework (Next.js) already has to know:

  • Which routes are SSG (getStaticProps), ISR (revalidate: N), SSR (getServerSideProps), or dynamic (API / middleware / edge functions).
  • Whether the route returns user-specific data (auth headers, cookies).
  • Whether the route is deterministic on the request URL + method.

This information must exist at build time — the framework uses it to decide what to render at build time vs. runtime, what to include in the static manifest, what bundler splits to make. The framework-inferred-cache-policy pattern takes this already-computed information and hands it downstream to the CDN instead of asking the developer to re-declare it.

The result is a zero-config adoption surface: any app that upgrades Next.js and redeploys on Vercel automatically gets request collapsing on its ISR routes. No code change, no CDN config, no migration window.

Vercel's production shape

(sources/2026-04-21-vercel-preventing-the-stampede-request-collapsing-in-the-vercel-cdn)

"Vercel solves this through framework integration. When you deploy your app, Vercel analyses your routes and understands which ones use ISR, static generation, or dynamic rendering. This metadata gets distributed to every CDN region. When a request arrives, the CDN already knows whether that specific route can be safely cached and collapsed. This happens without any configuration from you. The framework's code tells Vercel how each route behaves, and Vercel applies the correct caching strategy automatically, including features like request collapsing."

Three explicit classes the CDN distinguishes:

Route type Collapsible? Reason
ISR page (same content for all users) ✓ Deterministic, shared
Dynamic API route (user-specific data) ✗ Per-user response
Page with random content / timestamps ✗ Non-deterministic

Why the CDN can't infer this itself

A CDN that only sees HTTP requests (without deployment metadata) has no reliable way to tell whether a 200 response can be shared across users. It can look at:

  • Cache-Control headers — but developers set these wrong routinely, and Vercel's default is no-cache for safety.
  • Response uniqueness — requires sampling, introduces races.
  • Route patterns — /api/* is a hint but not authoritative.

The framework, by contrast, knows definitively because the developer wrote getStaticProps (SSG), revalidate: 60 (ISR), or getServerSideProps (SSR). This is the information the pattern leaks out to the CDN.

Companion primitives

  • Route classification in the build output. The framework emits a route manifest (Next.js's .next/routes-manifest.json is the canonical file) that enumerates every route and its rendering strategy.
  • Per-region metadata distribution. The CDN must have the metadata at the edge when a request arrives. Upload as part of the deployment artifact; replicate to each region's routing-service config. See systems/vercel-routing-service for the sibling metadata- distribution path (the routing-service distributes a Bloom filter of path existence per deployment).
  • Versioned metadata. When a deployment ships, its metadata must become live atomically with the routes, lest the CDN apply stale caching rules to new routes.

Alternatives considered

  • Developer-annotated cache policy. Most naive. Each route has a cache: 'collapsible' annotation. Error-prone: default choice is wrong (developer forgets or picks wrongly); adoption requires mass migration.
  • Explicit CDN config file (Cloudflare _headers, Vercel's vercel.json). Better than per-route annotations but still a separate source of truth that can drift from the application code.
  • Cache-Control header enforcement. Use RFC semantics — but Cache-Control: public alone doesn't imply "safe to collapse"; collapsing also requires determinism within the TTL.
  • Per-request learning. CDN observes response variance over time and auto-decides. Requires a learning window; wrong during cold start; unclear failure mode.

None of these match framework-inferred's zero-config adoption surface; most require developer engagement that the framework integration renders unnecessary.

Coupling cost

The pattern creates a tight coupling between the framework and the CDN:

  • Next.js route semantics become part of Vercel CDN's API surface.
  • A new Next.js route type (e.g. React Server Components, PPR) requires matching CDN logic.
  • Other frameworks (SvelteKit, Astro, Nuxt) need separate adapters if they want the same treatment.

For a vertically integrated vendor (framework + runtime + CDN all from Vercel), the coupling cost is cheap — both sides ship together. For an independent CDN wanting to support multiple frameworks, this is a real integration tax; see patterns/two-phase-framework-integration-pattern for generalisations.

Seen in

  • sources/2026-04-21-vercel-preventing-the-stampede-request-collapsing-in-the-vercel-cdn — canonical Vercel application: per-route ISR / SSG / dynamic metadata inferred from the Next.js build output and used by the CDN to decide request-collapsing eligibility with no user configuration.
  • Related earlier Vercel applications: Next.js route-rewrite metadata (content-negotiation ingest); Bloom-filter of deployment paths in systems/vercel-routing-service; both are the same pattern at different altitudes (routing-service learns which paths exist; CDN learns which paths are cacheable).
Last updated · 476 distilled / 1,218 read