Support building route-aware server reference manifests

[hi-ogawa]

Trying to capture background context and high level motivation for

• feat(rsc): support observing imports/exports during build scan #1278
• fix(app-router): align server action routing cloudflare/vinext#2520

Following is an AI-assited write-up. I steered the high level picture and get the vibe but haven't reviewed much:

---

Motivation

plugin-RSC currently generates a server-reference registry containing dynamic imports for all discovered server references in an RSC server build. When every route is handled by that same build and registry, each reference is globally addressable and can be loaded lazily on first use. A route-aware manifest is not necessary for that architecture.

A framework may instead choose to create route-scoped server outputs, independently deployed workers, or route-specific action policies. In those architectures, different route entrypoints intentionally have access to different server references. The framework then needs to determine which entrypoints consume or can load each reference.

A route-aware server-reference manifest would let a framework:

• determine which route entrypoints can load each server reference;
• route a request to a compatible entrypoint when the current one cannot load it;
• validate that an action is reachable from the relevant application graph;
• support future deployment models in which route entrypoints become separate server bundles or workers.

Vinext is exploring such route-scoped availability for future multi-entrypoint or multi-worker deployments. It can derive the required relationships by separately parsing application modules and reconstructing their import and re-export graph, but that duplicates work already performed by the RSC build pipeline, requires careful coordination with RSC transforms, and risks observing source at the wrong stage.

The requested capability is therefore not a change to plugin-RSC's default global lazy-loading model. It is build-time information that lets framework integrations deliberately construct narrower route boundaries.

Example Scenario

Consider a framework that builds /dashboard and /settings as route-scoped server outputs:

1. /dashboard consumes a server function that is included in the /dashboard output but intentionally absent from /settings.
2. An action request reaches the /settings output, for example after navigation or through an external router.
3. /settings cannot resolve that reference from its route-scoped registry.
4. The framework consults a build-generated manifest and finds that /dashboard can load it.
5. The framework forwards the request to /dashboard or applies its own rejection policy.

The manifest could conceptually contain:

{
  "server-reference-id": {
    "entrypoints": ["/dashboard"]
  }
}

The exact output boundaries, manifest schema, request transport, and routing policy remain framework responsibilities. The RSC plugin only needs to expose enough stable build-time information for a framework to derive this relationship without performing a second full source crawl.

Requested Capability

Provide framework integrations with sufficient build-time information to derive which server references are consumed by or reachable from framework-defined entrypoints.

The supported capability should describe the available information and its lifecycle guarantees rather than require a particular implementation such as lexer callbacks or scan-build observers.

Potentially relevant information includes:

• server-reference IDs and their defining modules;
• whether a reference is a module export or a generated inline export;
• module import and re-export relationships as observed by the RSC build;
• the environment in which a module is scanned;
• build boundaries or reset events needed to discard stale observations;
• final bundler module information for correlating framework entrypoints with reachable modules.

Implementation Strategies to Evaluate

There may be a substantially simpler alternative to exposing source and lexer observations. The appropriate design depends on whether frameworks need module-level availability or exact export-level consumption.

Module Reachability

plugin-RSC could tag server-reference modules through Rollup ModuleInfo.meta, or otherwise expose their existing server-reference metadata. A framework could then traverse getModuleInfo(entry).importedIds and dynamicallyImportedIds from each route entrypoint and associate every server reference exported by a reachable module with that route.

Conceptually:

route entrypoint
  -> traverse resolved ModuleInfo edges
  -> find reachable server-reference modules
  -> associate their server references with the route

This resembles plugin-RSC's existing client-reference build flow, which records "use client" modules and later associates them with emitted RSC chunks during generateBundle.

It also matches the verified Next.js Webpack strategy for server actions. Next.js traverses each page entrypoint's reachable module graph and, when it encounters a module carrying server-action metadata, associates every action ID recorded for that module with the page. Although the same traversal tracks imported identifiers when building client-component entries, its server-action collection does not filter action IDs by the specific imported binding.

Advantages:

• uses Vite/Rollup's resolved module graph;
• requires little or no additional source parsing;
• naturally handles aliases and ordinary static or dynamic module reachability;
• may be sufficient when the manifest is used only to find a route capable of loading an action.

Tradeoff:

• module reachability produces a coarse candidate set. If a module is reachable through a helper export or side-effect import and also exports ten actions, all ten may be associated with the route. This is conservative and may be the correct definition when the route output or its server-reference registry can load the whole module.

Specifier-Sensitive Scan Graph

The approach explored by Vinext and PR #1278 combines resolved ModuleInfo with original source and es-module-lexer import/export metadata. Vinext reconstructs named, default, and namespace imports, aliases, barrels, star re-exports, cycles, dynamic imports, and generated inline action exports.

This can narrow the candidate set for common ESM patterns. For example, when a route graph imports only actionA from a module exporting actionA and actionB, it can associate only actionA with the route.

It is not exact semantic consumption analysis. A server reference is an ordinary runtime value after it enters a module and can be stored in an object, aliased through local variables, returned from a function, passed through props, or re-serialized. Import/export syntax identifies where a reference identity enters the module graph, but it does not trace arbitrary value flow inside that graph.

For example, a syntactic re-export tracker may not understand relationships such as:

import { action } from './actions'

const wrapped = { action }
export { wrapped }

A namespace import or unconstrained dynamic access generally has to fall back to all exports. References introduced through runtime data rather than a statically analyzable module edge cannot be assigned reliably by either strategy.

Advantages:

• can distinguish imported action bindings for common static ESM patterns;
• avoids assigning unrelated exports from the same server-reference module;
• can produce smaller route-specific action sets when its supported syntax is sufficient.

Costs:

• exposes low-level scan lifecycle and lexer details from plugin-RSC;
• requires framework code to reconstruct JavaScript import and re-export semantics;
• duplicates complex graph interpretation across framework integrations;
• creates more behavior to define for invalidation, transforms, virtual modules, and unusual import syntax.
• can under-approximate references propagated through syntax or runtime value flow it does not model.

Final Output Analysis

A third option is to derive availability from final chunks and renderedExports, similar to client-reference grouping. This may work well when each route is built as an isolated output. In a multi-entry build, shared chunks, re-export barrels, and plugin-RSC's global server-reference registry can make it difficult to recover exact per-route export consumption from final output metadata alone.

The feature request should first establish the required correctness model. If the manifest must conservatively include every action a route might receive, module reachability is easier to reason about and may be preferable. Specifier-sensitive tracking is useful as an optimization only if its supported propagation rules and fallback behavior are explicit.

The module-reachability option is therefore not merely a simplified approximation invented for plugin-RSC. It is close to the model used by Next.js for its route-to-action worker manifest. Vinext's proposal attempts to be narrower than that prior art.

A syntactic consumption graph should not by itself be treated as a security boundary. If the manifest is intended as an authorization allowlist, arbitrary value propagation, dynamic loading, retained client references, and references received through serialized data need a defined conservative fallback. Even then, plugin-RSC could potentially expose a higher-level graph rather than raw lexer observations.

Expected Outcome

A complete example should demonstrate a framework integration that:

1. deliberately builds at least two route-scoped RSC server outputs with different reachable server references;
2. derives which server references each entrypoint can load;
3. emits a route-aware server-reference manifest;
4. sends an action request to a route whose entrypoint cannot load it;
5. forwards the request to a compatible entrypoint or rejects it based on the manifest;
6. obtains the required information without reparsing every source module in a separate framework pass.

The example can run both outputs in one process and route between them by pathname. Physical worker isolation is not required to prove that the generated availability relationship is correct.

Scope Boundary

The RSC plugin should provide the build-time facts needed to derive entrypoint-to-reference relationships. It should not initially prescribe:

• how frameworks define routes or entrypoints;
• whether an entrypoint is deployed as a worker, function, process, or server bundle;
• how action requests are transported between entrypoints;
• which compatible entrypoint a framework should prefer when several can load an action;
• framework-specific authorization or request validation policy;
• a universal manifest schema unless common requirements emerge from integrations.

Open Questions

• Which build-time facts are stable enough to expose as a supported plugin API?
• Can final bundler module graphs provide the required reachability information, or are source-level import and re-export edges also necessary?
• Is module-level conservative assignment sufficient for request routing, and what concrete optimization requires a narrower specifier-sensitive candidate set?
• Which server-reference propagation patterns must the manifest handle, and what is the conservative fallback when static syntax cannot represent them?
• At which build phase can an integration reliably correlate transformed server references, original modules, and framework entrypoints?
• How should watch-mode invalidation and repeated environment builds reset collected state?
• Is inline-versus-module-level server-reference metadata part of this capability or an independent generally useful feature?
• Should plugin-RSC expose lower-level observations for frameworks to interpret, or provide a higher-level entrypoint reachability abstraction?
• What is the smallest end-to-end fixture that proves the capability without embedding one framework's routing architecture in plugin-RSC?

Prior Art and Context

Next.js generates a server-reference manifest that maps each action ID to the App Router page entrypoints capable of loading it. If the current page entrypoint cannot load an action, Next.js selects another compatible page entrypoint and internally forwards the request to its pathname.

Detailed research on Next.js server-action manifests and forwarding

• Next.js manifest schema
• Next.js route graph collection
• Next.js worker selection
• Next.js forwarding handler
• Next.js delayed-action forwarding e2e

Next.js needs this mapping because server actions are compiled into route-specific page entrypoint graphs. Lazy loading can load a known chunk from the current graph, but it cannot load an action that has no module mapping in that entrypoint. Next.js calls these page entrypoints workers, but this mechanism does not directly select a process, lambda, or deployment.

In the verified Webpack implementation, “a page uses an action” is determined conservatively through module reachability. Reaching a module with server-action metadata associates all action IDs from that module with the page. Next.js does not reconstruct named import and re-export semantics to narrow this action set.

This differs from plugin-RSC's current global registry, which emits a dynamic import for every discovered server reference in the server build. The Next.js navigation race is therefore prior art for route-scoped action availability, not evidence that every RSC integration needs route-aware forwarding.

• plugin-RSC global server-reference registry
• plugin-RSC lazy reference loading

vite-plugin-react PR #1278 proposes observing imports and exports during RSC scan builds and recording inline export names. This is one possible implementation or prerequisite, rather than the feature definition.

Vinext PR #2520 explores using that information to derive action availability. Vinext is also interested in future multi-entrypoint or multi-worker deployments, where a framework could use the same manifest to route requests between independently deployed entrypoints.

[hi-ogawa]

This is a follow-up note after checking through Vinext approach with concrete counter example cloudflare/vinext#2743 and also prototyping an alternative in #1341. Still evaluating the ideas but getting this context out there first.

---

The initial issue framing missed an important part of the problem: route-to-server-reference reachability crosses two different environment graphs.

Consider:

Server Component route
  -> Client Component reference
      -> ordinary client helper modules
          -> server-reference proxy

The final RSC graph can tell a framework that the route reaches the Client Component reference, but the Client Component's dependencies have been replaced by the RSC-side proxy. The action edge only remains visible in the final client graph.

Therefore, traversing only the final RSC ModuleInfo graph is not sufficient. A framework needs to join:

route -> reachable Client Component references       (final RSC graph)
Client Component reference -> reachable server refs  (final client graph)

The second relation is the plugin-RSC-specific missing primitive.

Why Import/Export Reconstruction Is Not Sufficient

Vinext's current experiment reconstructs named imports, aliases, and re-exports from scan-time es-module-lexer records. That can provide narrower results for common ESM patterns, but it is not sound as the sole source of action reachability because server references are ordinary JavaScript values.

A minimal counterexample is:

// client-form.jsx
'use client'

import { commands } from './commands.js'

export function ClientForm() {
  return <form action={commands.objectWrappedAction}>...</form>
}

// commands.js
import { objectWrappedAction } from './action.js'

export const commands = { objectWrappedAction }

// action.js
'use server'

export async function objectWrappedAction() {}

The browser has a valid server-reference proxy and submits its action ID. However, import/export reconstruction cannot infer that the ordinary commands export carries objectWrappedAction. In the Vinext production reproduction, this omitted the action from the owner manifest and caused a framework-level action-not-found response.

The final client module graph retains the relevant conservative relationship without tracing JavaScript values:

client-form.jsx -> commands.js -> action.js server-reference proxy

Proposed Core Capability

plugin-RSC could expose semantic build metadata equivalent to:

Client Component reference -> server-reference IDs reachable in its client graph

For example:

type ClientReferenceServerReferences = {
  importId: string
  referenceKey: string
  serverReferenceIds: readonly string[]
}

This relation can be computed during the final client build by traversing ModuleInfo.importedIds and ModuleInfo.dynamicallyImportedIds from each discovered Client Component reference and recognizing server-reference modules through plugin-RSC's existing metadata.

This seems to fit plugin-RSC because it owns:

• the RSC and client environment boundary;
• Client Component reference identities;
• transformed server-reference proxy identities;
• server-reference IDs;
• client-reference grouping and client build orchestration.

Framework integrations should not need to recognize generated proxy source or correlate private virtual module IDs across environments.

Framework Responsibility

The higher-level route manifest should remain framework-specific. A framework such as Vinext would:

1. Define its route roots, layouts, slots, and other contributing modules.
2. Traverse the final RSC graph from each route.
3. Collect directly reachable and generated inline server references.
4. Collect reachable Client Component references.
5. Join those client references with plugin-RSC's client-to-server reachability metadata.
6. Emit its own route manifest and apply its own forwarding or rejection policy.

This keeps routes, middleware, deployment topology, manifest schema, and request transport outside plugin-RSC.

Prototype Result

PR #1341 prototypes this relation as RscPluginManager.clientReferenceServerReferences and adds a dedicated examples/action-reachability application.

The production E2E verifies both that:

• final client ModuleInfo traversal connects the object-wrapped Client Component to objectWrappedAction;
• the browser invokes the same object-wrapped server reference successfully through plugin-RSC's existing runtime.

The generated result is conceptually:

{
  "/src/client-form.jsx": {
    "referenceKey": "client-reference-key",
    "serverReferenceIds": ["server-reference-key#objectWrappedAction"]
  }
}

The current build order is not a blocker. A framework can retain the RSC-side relation during the RSC build, consume the client-side relation after the client build, and write its completed manifest as an external ESM sidecar in a post-buildApp hook, following plugin-RSC's existing assets-manifest technique.

Semantics and Limits

This should be conservative module reachability, not exact JavaScript value-flow analysis.

If a reachable server-reference module exports several actions, an initial implementation may associate all of them with the Client Component reference. That can produce false positives, but it avoids the demonstrated false negative and has a clear meaning for code availability and dispatch.

This relation is not authorization. Route ownership and middleware forwarding can be useful framework policy, but server references remain transferable runtime values and actions still require action-local authentication and resource authorization.

Updated Feature Shape

The core plugin-RSC request can therefore be narrowed from “support building route-aware manifests” to:

Expose stable cross-environment metadata that maps each Client Component reference to server references reachable through its final client module graph, while retaining direct and inline server-reference metadata for framework-side RSC traversal.

This provides the RSC-specific graph bridge. Frameworks can build route-aware manifests on top without depending on raw scan source, lexer records, or plugin-RSC's generated proxy implementation.

[hi-ogawa]

Another follow-up notes while landing #1341

• The PR adds an end-to-end example that derives a route/action manifest from the final RSC and client module graphs, then uses it to redispatch a retained action after navigation so it passes through the middleware of the page where the action is originated from.
  • This example didn't require any new core plugin level feature as the action module reachability can be obtained through existing manager API and Vite's module graph API during build. The proposed API in the comment above was therefore removed, and further core API design is postponed and moved to a separate draft PR
  • The example's action redispatch mechanism is production-only since it relies on build-time manifest. I haven't explored how the same module reachability analysis could be achieved on dev. This can lead to dev/prod inconsistency but I think this is less of an issue since, in practice, action re-routing shouldn't happen since action is consumed inside the same page (i.e. where reachable as module graph). So the behavior sounds reasonable if treating this as minor security hardening.
• The related Next.js investigation also found a confirmed routing limitation. Routing considers only the explicit outer action ID. Passing a retained server reference as an argument, such as actionB(savedActionA), fails during decoding when the selected page's module map cannot resolve the nested reference. This was reproduced with both Webpack and Turbopack in development and production.
  • reproduction: https://github.com/hi-ogawa/reproductions/tree/main/next-rsc-action-argument
  • reported to Server Action passed as an argument fails when called after navigation vercel/next.js#96331

Updated Next.js research: https://gist.github.com/hi-ogawa/891bb0b74399261dfe974bf443b8b069

---

One note, the example added by #1341 is not a full conclusion of this issue because it doesn't yet demonstrate the desired deployment model where the framework can deploy multiple request handler entry points based on route and server action module reachability.

[hi-ogawa]

Another follow-up after digging into action re-routing idea.

The discussion so far may have indicated it's a solved problem, but in practice (and especially re-routing through per-route deployment), it appears that server-side action request forwarding seems to have some foot guns (and Next.js has explored the alternative to avoid server-side re-routing in the past vercel/next.js#90549).

I have updated Next.js research note to include that aspect: https://gist.github.com/hi-ogawa/891bb0b74399261dfe974bf443b8b069#additional-internal-forwarding-failure-modes

Also also created a separate (unreviewed) note for what it would look like to implement client-side action re-routing approach: https://gist.github.com/hi-ogawa/4f88a7f6e51c04b37eb25c81a9faae21