Runtime Integration

Core Idea

The Deployment Adapter API is build-time only; actual request handling, streaming, and caching happen through the Next.js server and the separate cacheHandler/cacheHandlers runtime cache interfaces.

Key Concepts

• Adapter (build-time): processes build outputs, configures routing, sets up platform infra.
• Cache Interfaces (runtime): cacheHandler manages ISR/server cache storage and revalidation across instances; cacheHandlers configures 'use cache' directive backends and tag coordination.
• ctx.waitUntil: function accepting a promise, passed to the Next.js handler, keeps a serverless function alive after the response is sent so background work (e.g. cache revalidation) can finish.
• requestMeta.onCacheEntryV2: callback (set via addRequestMeta) firing whenever a cache entry is generated or looked up; fires only on the instance that handled the request, so multi-instance deployments must propagate updates to shared storage.
• PPR chain headers (pprChain.headers): { 'next-resume': '1' }, required on the resume request when serving a cached PPR shell separately (POST with postponedState as body).

Reference Tables

Concept	Layer	Purpose
Adapter	Build-time	Build outputs, routing config, platform setup
cacheHandler	Runtime	ISR/server cache storage + revalidation
cacheHandlers	Runtime	'use cache' backend + tag coordination
ctx.waitUntil	Runtime handler ctx	Keep function alive for background work
requestMeta.onCacheEntryV2	Runtime handler ctx	Observe/propagate all cache operations

Anti-patterns

• Assuming onCacheEntryV2 propagates across instances automatically: it fires only on the instance handling the request; multi-instance deployments must explicitly forward updates to shared storage.

Key Takeaways

1. Adapters own build-time wiring; runtime behavior is a separate contract via cacheHandler/cacheHandlers.
2. ctx.waitUntil is the standard serverless pattern for post-response background work in Next.js handlers.
3. The PPR resume protocol is a deliberate escape hatch for CDN-to-origin architectures wanting to serve the static shell separately from next start's single-pass default.

Connects To

• ch276 implementing-ppr-in-an-adapter: concrete usage of onCacheEntryV2 and the resume protocol.
• ch278 invoking-entrypoints: where ctx (including waitUntil, requestMeta) is passed into the handler call.