PPR: build-time shell capture (prerender × ppr) #649

Activity

1. ivogt commented on Jul 3, 2026

   

   ivogt

   on Jul 3, 2026

   CollaboratorAuthor

   More actions

   API design discussion outcome (2026-07-04):

   Considered and rejected:

   • Ppr(handlerThatRuns) handler wrapper (a Prerender-style sibling). Right instinct — no handler eviction, since the HIT tail / hole loaders / expiry recapture still need the handler at runtime — but it creates a second PPR declaration syntax for behavior that is indistinguishable at serve time. Build-time vs runtime capture is eagerness of the same cache write ("pre-rendering IS caching, just at build time"), not a different route semantic.
   • Extending Static() to carry shell-ness (layout(Static(...))). Category error: Static is segment-granular, the shell is a document property — the same granularity mismatch that killed cache({ ppr }). Static/Prerender instead COMPOSE with shell capture: they make shell content build-deterministic; the snapshot pins the rest.

   Chosen direction: extend the ppr prop with enumeration — the one genuinely build-specific input:

   path("/blog/:id", BlogPost, {
     name: "post",
     ppr: { ttl: 600, build: () => posts.map(p => ({ id: p.slug })) },
   });
   path("/pricing", Pricing, { name: "pricing", ppr: { ttl: 3600, build: true } });

   One declaration site (route line reads "PPR'd, and seeded at build"); build hook lives beside Prerender's closeBundle walk; existing capture machinery runs against a synthetic request; putShell + snapshot into the runtime store; handler and serve path untouched.

   Open questions sharpened by this shape:

   • Shell keys are host-scoped and PPR shell tags via render-callable cacheTag() (API settled: no variant keys — the URL is the key) #648's key(ctx)/tags(ctx) are request-derived — build has no request. Options: configured build host + enumerated variants, or hybrid (build warms the default variant, runtime capture fills the rest).
   • Transport unchanged from the issue body: build-time store writes (KV binding at build) vs a seed artifact applied at deploy.
2. ivogt commented on Jul 3, 2026

   

   ivogt

   on Jul 3, 2026

   CollaboratorAuthor

   More actions

   Enumeration API refinement (supersedes the ppr.build field from the previous comment):

   Use the DSL's reverse-form named-route language for the build manifest instead of per-route enumerate fns — a build() manifest of typed path(name, params) entries:

   export const shellBuild = build(({ path }) => [
     path("pricing"),
     path("post", { id: "hello-world" }),
     ...posts.map((p) => path("post", { id: p.slug })),
   ]);
   
   createRouter({ urls: patterns, build: shellBuild });

   Why this beats ppr: { build: getParams }:

   • Typed end-to-end against GeneratedRouteMap (wrong/missing params = TS error; route rename breaks entries at typecheck), vs stringly { id } objects.
   • One visible build surface instead of fns scattered across route options.
   • Cross-route enumeration from one data source in one expression.
   • Generalizes: the same manifest vocabulary can later drive classic Prerender (B segments) too — one build-instance language for both artifacts.

   Division of labor: the route's ppr prop declares BEHAVIOR; the build() manifest picks INSTANCES. A manifest entry naming a route without ppr is a build error (until/unless it grows a plain-Prerender meaning).

   Rejected sibling reading: build.path(pattern, Handler, ...) as a marker variant of the route-defining path() — splits the declaration across combinator + prop (same critique that killed Ppr(handler)), and the path() overload surface is fragile (#642 scar).

   Still open (unchanged): host + variant keying without a live request; build-store transport. Async manifest entries should be supported (data-driven enumeration needs awaits — same precedent as Prerender's getParams).
3. ivogt commented on Jul 3, 2026

   

   ivogt

   on Jul 3, 2026

   CollaboratorAuthor

   More actions

   Enumeration direction superseded again, final form: the build() reverse-form manifest from the previous comment is dropped in favor of the build.* DSL namespace — see the full proposal in the new issue. Enumeration colocates on build.path(..., { params }) (today's getParams moved into the options bag), and a route that is both build.path'd and ppr'd gets its shells captured at build for the enumerated instances — the intersection principle expressed entirely in the tree. Eviction rule: ppr routes retain their handler (tail/holes/recapture need it); plain build.path keeps Prerender's eviction.
4. ivogt

   closed this as completedon Jul 6, 2026