fix(router): preserve embedded server actions across cache and prerender hits

[ivogt]

Problem

Embedding a server-created inline "use server" action inside a cached or build-time-prerendered value can fail on the cache/prerender hit. The canonical case is an article list whose like action captures the article id but reads the current user from the live request:

export async function ArticleList() {
  "use cache: articles";
  const articles = await db.query("SELECT id, title FROM articles");

  return articles.map((article) => {
    async function like() {
      "use server";
      const user = cookies().get("session")?.value;
      if (user) await db.like(article.id, user);
    }

    return <LikeButton key={article.id} action={like} />;
  });
}

The required contract is:

• Captured render scope is frozen when the cache/prerender entry is written.
• The action body executes live on every invocation.
• Request context, including cookies, comes from the live action POST.

Before And After

Scenario	Before	After
"use cache" embedded action, Node memory store	hit can fail with a missing server reference	works
"use cache" embedded action, Cloudflare cross-process store	hit fails to re-serialize the action	works with preserved references
Static() embedded action	production hit cannot resolve/re-serialize the action	works with preserved references
Parameterized Prerender() embedded action	production hit cannot resolve/re-serialize the action	works with preserved references

Root Cause And Fix

A server-created action in stored Flight must survive serialize -> store -> deserialize -> re-serialize -> invoke. Five pieces now line up:

1. Stable production id - build discovery runs through a temporary dev Vite server. hashServerRefs rewrites its dev-style server-reference ids to the production hashes stored in the real manifest.
2. Correct scan graph - plugin-rsc strips scan modules to imports before the existing post-order loader transform can stub export-only createLoader modules. Their server implementation dependencies then leak into non-RSC analysis. A dedicated build-only pre-scan plugin emits loader stubs first while leaving RSC and normal builds unchanged. Real Node and Cloudflare loader fixtures import server-only to pin this ordering.
3. Re-serializable references - segment-codec uses the third-argument preserveServerReferences option released in @vitejs/plugin-rsc@0.5.30, keeping references opaque instead of resolving them to raw functions that React refuses to pass to a Client Component.
4. Shared encryption key - the build-discovery server and main runtime receive the same defineEncryptionKey, so bound arguments captured during prerender can be decrypted when the action runs. RANGO_ENCRYPTION_KEY supports a stable deployment key.
5. Pure-Prerender action re-render - after the action runs, a non-Passthrough Prerender route falls back to its stored entry because its build-only handler no longer exists. Passthrough routes retain their live handler and still re-render fresh.

The earlier serverReferenceMetaMap re-assertion workaround has been removed. Keeping loader implementation imports out of the non-RSC scan fixes the ordering problem at its source.

Main Changes

• Added server-reference hashing for build-discovery output.
• Added the shared encryption-key strategy for Node and Cloudflare dev/build paths.
• Preserved embedded server references at every segment-codec decode site.
• Added the pure-Prerender action re-render fallback.
• Added the pre-scan export-only loader stub and scan-ordering unit coverage.
• Added realistic use cache, Static, parameterized Prerender, Node loader, and Cloudflare/workerd fixtures.
• Documented frozen capture versus live action-body and request-scope semantics.
• Raised the @vitejs/plugin-rsc minimum to ^0.5.30 and removed the preview override.

Verification

• Stable @vitejs/plugin-rsc@0.5.30 migration: Node embedded-action matrix passed 6/6 in dev and production.
• Stable @vitejs/plugin-rsc@0.5.30 migration: Cloudflare/workerd embedded-action matrix passed 4/4 in dev and production.
• Node e2e: cached, Static, Prerender, and orphan fetchable-loader scenarios in dev and production.
• Cloudflare/workerd e2e: cached/prerender inline actions and orphan fetchable loader in dev and production; full run passed 365 tests with 2 intentional skips.
• Route HMR: 18/18.
• Unit and RSC suites: all passing.
• Monorepo typecheck, lint, and format: all passing.
• E2E bucketing and parity guards: passing.

Dependency

This fix requires @vitejs/plugin-rsc@^0.5.30, the first stable release with preserveServerReferences support.

Fixes #585

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@rangojs/router@584

commit: 1e44a18

[ivogt]

Reconfirmed against current main plus #768: runtime-captured PPR does not inherit this blocker. Closure-bound inline actions survive both document shell HIT hydration/invocation and partial PPR navigation/invocation in dev and production, in the router app and the Cloudflare/KV app. Coverage is in #769. This does not change #584's build-time Static/Prerender status or its dependency on vitejs/vite-plugin-react#1246.