[PR #924] [MERGED] fix(cache): scope use cache entries by build id #951

New issue

Closed

opened 2026-05-06 13:11:12 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-06 13:11:12 +02:00

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/vinext/pull/924
Author: @NathanDrake2406
Created: 4/28/2026
Status: ✅ Merged
Merged: 4/28/2026
Merged by: @james-elicx

Base: main ← Head: nathan/use-cache-build-id

📝 Commits (2)

de3e29c fix(cache): scope use cache entries by build id
548d494 fix(cache): capture use cache build id at registration

📊 Changes

2 files changed (+59 additions, -5 deletions)

View changed files

📝 packages/vinext/src/shims/cache-runtime.ts (+22 -5)
📝 tests/shims.test.ts (+37 -0)

📄 Description

What this changes

Shared "use cache" entries now include the vinext build ID in their persistent cache key before the cached function ID and serialized arguments. Environments without a build ID keep the previous key shape.

Why

Persistent handlers such as Workers KV can outlive a deploy. Before this change, vinext keyed shared "use cache" entries as function ID plus arguments, so a new deployment could read a serialized RSC result produced by an older function body when the generated ID and arguments stayed stable.

Next.js includes buildId as the first part of the "use cache" key material:

Approach

registerCachedFunction() now reads process.env.__VINEXT_BUILD_ID and uses it to scope shared cache entries as build-specific keys. The read keeps a direct process.env.__VINEXT_BUILD_ID reference so Vite can inline the value for Worker bundles, and it only recovers the missing process global case.

The key builder encodes custom build IDs before placing them in the colon-delimited key, which avoids delimiter collisions without changing key shape when no build ID exists.

Validation

git diff --check
vp test run tests/shims.test.ts -t 'scopes shared cache entries by build ID'
vp test run tests/shims.test.ts -t '"use cache" runtime'
vp check packages/vinext/src/shims/cache-runtime.ts tests/shims.test.ts
vp test run tests/shims.test.ts
vp run vinext#build

Risks / follow-ups

This intentionally invalidates existing shared "use cache" entries on the next deploy when a build ID is available. That is the desired Next.js-compatible behavior for code-derived cached RSC streams.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/cloudflare/vinext/pull/924 **Author:** [@NathanDrake2406](https://github.com/NathanDrake2406) **Created:** 4/28/2026 **Status:** ✅ Merged **Merged:** 4/28/2026 **Merged by:** [@james-elicx](https://github.com/james-elicx) **Base:** `main` ← **Head:** `nathan/use-cache-build-id` --- ### 📝 Commits (2) - [`de3e29c`](https://github.com/cloudflare/vinext/commit/de3e29ce4dc003b30cdd78bbc0181975b4f574ac) fix(cache): scope use cache entries by build id - [`548d494`](https://github.com/cloudflare/vinext/commit/548d4945fcc2a2403c05c12f83e9cda3875d66b1) fix(cache): capture use cache build id at registration ### 📊 Changes **2 files changed** (+59 additions, -5 deletions) <details> <summary>View changed files</summary> 📝 `packages/vinext/src/shims/cache-runtime.ts` (+22 -5) 📝 `tests/shims.test.ts` (+37 -0) </details> ### 📄 Description ## What this changes Shared `"use cache"` entries now include the vinext build ID in their persistent cache key before the cached function ID and serialized arguments. Environments without a build ID keep the previous key shape. ## Why Persistent handlers such as Workers KV can outlive a deploy. Before this change, vinext keyed shared `"use cache"` entries as function ID plus arguments, so a new deployment could read a serialized RSC result produced by an older function body when the generated ID and arguments stayed stable. Next.js includes `buildId` as the first part of the `"use cache"` key material: - [Next.js `CacheKeyParts` tuple includes `buildId`](https://github.com/vercel/next.js/blob/canary/packages/next/src/server/use-cache/use-cache-wrapper.ts#L105-L107) - [Next.js comment explaining build ID is needed because action IDs are not unique per implementation](https://github.com/vercel/next.js/blob/canary/packages/next/src/server/use-cache/use-cache-wrapper.ts#L1509-L1513) - [Next.js runtime constructs cache keys with `buildId`](https://github.com/vercel/next.js/blob/canary/packages/next/src/server/use-cache/use-cache-wrapper.ts#L1682-L1684) - [Next.js custom cache handler test expects `buildId` as the first serialized key element](https://github.com/vercel/next.js/blob/canary/test/e2e/app-dir/use-cache-custom-handler/use-cache-custom-handler.test.ts#L30-L35) ## Approach `registerCachedFunction()` now reads `process.env.__VINEXT_BUILD_ID` and uses it to scope shared cache entries as build-specific keys. The read keeps a direct `process.env.__VINEXT_BUILD_ID` reference so Vite can inline the value for Worker bundles, and it only recovers the missing `process` global case. The key builder encodes custom build IDs before placing them in the colon-delimited key, which avoids delimiter collisions without changing key shape when no build ID exists. ## Validation - `git diff --check` - `vp test run tests/shims.test.ts -t 'scopes shared cache entries by build ID'` - `vp test run tests/shims.test.ts -t '"use cache" runtime'` - `vp check packages/vinext/src/shims/cache-runtime.ts tests/shims.test.ts` - `vp test run tests/shims.test.ts` - `vp run vinext#build` ## Risks / follow-ups This intentionally invalidates existing shared `"use cache"` entries on the next deploy when a build ID is available. That is the desired Next.js-compatible behavior for code-derived cached RSC streams. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>