feat(prerender): seed KV cache with pre-rendered routes at deploy time

[raed04]

Summary

• Adds automatic KV cache population during vinext deploy so pre-rendered pages are cache HITs from the first request
• New deploy-time step reads vinext-prerender.json and uploads HTML/RSC entries to Workers KV via the Cloudflare bulk REST API
• Correct cache key format matching runtime KVCacheHandler.get(): cache:app:<buildId>:<pathname>:html

How it works

1. After pre-rendering completes (Step 6a) and before wrangler deploys the worker (Step 7), a new Step 6c runs automatically
2. Reads vinext-prerender.json manifest and pre-rendered HTML/RSC files from dist/server/prerendered-routes/
3. Constructs ISR cache keys via isrCacheKey() (same function the runtime uses)
4. Base64-encodes RSC data to match KVCacheHandler serialization format
5. Uploads in batches of 10,000 pairs via Cloudflare KV bulk REST API

Automatic when: CLOUDFLARE_API_TOKEN env var is set and VINEXT_CACHE KV namespace exists in wrangler config.
Opt-out: vinext deploy --no-seed-cache
Non-fatal: Seeding failures log a warning but never block deployment.

Key design decisions

• Correct key format — cache:app:<buildId>:<pathname>:html matches what KVCacheHandler.get() reads at runtime (unlike TPR which uses cache:<pathname> — a known pre-existing bug)
• Static routes omit expiration_ttl — matches runtime KVCacheHandler.set() behavior (no expiry for static pages)
• ISR routes get 10x revalidate TTL clamped to [60s, 30d]
• Deploy-time only — this module runs in Node.js during deploy, never bundled into the worker (addresses the bundle contamination concern from Populating remote cache during deployment #562)
• App Router only — Pages Router seeding is left for future work

Security

• Path traversal guard: resolved file paths must stay within prerenderDir
• TOCTOU-safe: uses try/catch on readFileSync (no existsSync + readFileSync race)
• Error messages capped to 500 chars to prevent sensitive data leakage
• Checks Cloudflare API success: false responses (HTTP 200 with semantic errors)

Files

File	Change
packages/vinext/src/cloudflare/seed-kv-cache.ts	New — core seeding module (300 lines)
packages/vinext/src/deploy.ts	Step 6c integration + --no-seed-cache flag
packages/vinext/src/cli.ts	Wire noSeedCache flag to deploy options
tests/seed-kv-cache.test.ts	New — 27 unit tests

Test plan

• 27 unit tests covering:
  • Correct KV key format with isrCacheKey()
  • Binary RSC base64 round-trip
  • FNV1a hash for long pathnames (>200 chars)
  • Static routes: null revalidateAt, no expiration_ttl
  • ISR routes: correct revalidateAt, TTL clamping (min 60s)
  • revalidate=0 treated as static
  • Unicode pathnames
  • Empty HTML files
  • Mixed manifest (App + Pages + skipped + error routes)
  • Batch splitting at 10,000 pairs with order preservation
  • API success:false rejection
  • API HTTP error handling
• All existing tests pass
• Formatting passes vp fmt --check

Closes #562

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/vinext@734

commit: fc51d75

[NathanDrake2406]

Hey bro, I've already attempted this #670
But for vinext, we're aiming for something that is more universally supported than just hardcoding KV like James said.