bundledDev: server-side API to map module id to served URL (needed for SSR modulepreload/hydration hints)

[ryansolid]

Description

SSR frameworks that stream HTML serialize per-module URLs into the document itself, ahead of any client code:

• <link rel="modulepreload" href="..."> hints, so the browser fetches lazy route chunks in parallel with the entry bundle during HTML parse, and
• a hydration module map (e.g. _$HY.r["…_assets"] = { hydrationKey: url }) written by inline <script> chunks in the stream, which the client runtime import()s before resuming server-rendered DOM.

Concrete case: SolidStart on solid-js 2.0 / vite-plugin-solid. In (unbundled) dev, the framework's asset resolver answers "what URL serves module X?" by identity — the module's dev URL, e.g.:

/src/routes/(basic).tsx?pick=default&pick=$css

Under experimental.bundledDev (Vite 8.1) that contract breaks:

• The served HTML (200) still contains those source-path URLs in the modulepreload hints and the hydration module map — the SSR side has nothing else to emit.
• Requesting the URL itself returns 404: only bundled output files are served (memoryFilesMiddleware looks up memoryFiles.get(pathname.slice(1)) and falls through for anything that isn't an output fileName).
• The client runtime's pre-hydration import(url) therefore rejects, hydration falls back to a fresh client render, and the page ends up with duplicated DOM. In SolidStart's test app this is 18 failing e2e specs (apps/tests e2e:bundled-dev) that all pass in normal dev.

The underlying gap: a server-side plugin has no API to translate a module id into its served URL in bundled dev.

• BundledDev.memoryFiles maps output fileName → { source, etag }. There is no facade/module-id → fileName mapping exposed, so you can't go from src/routes/(basic).tsx?pick=default&pick=$css to assets/_basic_-DhY….js.
• The lazy-compile endpoint /@vite/lazy?id=…&clientId=… (triggerLazyBundlingMiddleware → devEngine.compileEntry(moduleId, clientId)) requires a live HMR clientId and returns compiled code, not a URL — unusable from an SSR render pass that must emit URLs into HTML before any client connects.

Put differently: in normal dev, module → URL is answerable by identity (the URL is the module path); in production builds it's answerable via manifest.json. Bundled dev is currently the only topology that provides neither.

We want to stress this is a correctness requirement for streamed SSR hydration in bundled dev, not an optimization: the URLs are fixed server-side and shipped in the HTML before any client code executes, so there is no client-side recovery — either the server can emit servable URLs or hydration of code-split routes fails. We understand bundledDev is experimental and evolving; if there's an intended pattern for this that we've missed, pointers welcome, and we're glad to help test an API.

Suggested solution

A stable server-side API — on the client Environment or the dev server — that, under bundledDev, maps module id → served URL(s) (the entry chunk for that module, ideally with its static import chain for complete preload hints), e.g.:

const urls = await server.environments.client.bundledDev.resolveModuleUrl(
  "src/routes/(basic).tsx?pick=default&pick=$css"
);
// → ["/assets/_basic_-DhYx12ab.js", ...]

Semantics we'd need: awaits the current build if one is in flight (like waitForInitialBuildFinish), and reflects lazy-compiled entries once they exist (or triggers compilation without requiring a browser clientId).

Alternative

For the client entry specifically, SolidStart already works around this by hardcoding the served path, assets/${basename(entry)}.js, which is only possible because the entry's entryFileNames is predictable. Hashed lazy route chunks have no equivalent workaround — their served names are only knowable from the bundle graph Vite holds. Emulating a manifest by watching memoryFiles doesn't work either, since there's no exposed mapping from output files back to the facade module ids the framework knows about.

Additional context

Reproduction:

• Full suite: solidjs/solid-start repo, branch upgrade-to-solid-2-beta, apps/tests, pnpm e2e:bundled-dev (playwright.bundled-dev.config.ts) — 18 hydration-related failures; the same specs pass with pnpm e2e (unbundled dev).
• Minimal sketch: any Vite 8.1 app with experimental.bundledDev and an SSR handler that renders a code-split (import()-ed) component and emits <link rel="modulepreload"> / a script that import()s that module's dev URL (/src/Comp.tsx). The HTML streams fine; the module request 404s; anything gated on it fails — while the same URL works in unbundled dev.

Related precedent: solidjs/solid-start#2210 (the hardcoded entry-URL workaround mentioned above).

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[sapphi-red]

Thanks for the issue. Would you expand more on the dynamic entrypoints? It would probably interact with "lazy bundling" feature which defers the transform of dynamically imported modules.

[ryansolid]

Happy to expand — and yes, lazy bundling is exactly where this bites.

What our dynamic entrypoints are. Two flavors, both reached only via dynamic import:

1. Framework-generated route facades: the router plugin maps each route file to a virtual-ish module id with a query (src/routes/(basic).tsx?pick=default&pick=$css), and the generated route tree loads it with lazy(() => import(...)).
2. Ordinary user code-splitting: lazy(() => import("./HeavyComp")) anywhere in the tree.

Since nothing imports these statically, under lazy bundling every one of them is a deferred entry.

When we need their URLs. During the SSR render itself. As the server streams HTML, each server-rendered lazy component resolves its module id through the framework's asset resolver and we emit, into the stream:

• <link rel="modulepreload" href="..."> in the head, and
• hydration-map entries (inline <script> chunks) mapping hydration keys to module URLs.

The browser starts fetching those URLs during HTML parse, and the client runtime import()s the hydration-map URLs and blocks hydration resume on them. All of this happens before the client entry has executed — so before any HMR connection exists, i.e. before there is a clientId. That's why /@vite/lazy?id=…&clientId=… can't serve the first render/hydration of a code-split page: the consumer of the URL is the HTML we already sent, not a connected client.

What semantics would work for us. We don't actually need the compile to have happened at emit time — we need a stable URL we can emit that will serve the module's code when the browser requests it, compiling on demand at request time. Two shapes that would both solve it, in order of how well they seem to fit lazy bundling:

1. Facade URLs for lazy entries. If each deferred entry were addressable by a stable, unhashed URL derived from its module id (conceptually like unbundled dev's identity URLs), and the middleware triggered compileEntry when that URL is first requested (no clientId required, or one minted server-side), everything composes: we emit the facade URL during SSR, the browser's preload request is itself the compile trigger, and lazy bundling keeps its full deferral benefit — only routes actually rendered ever compile. This also sidesteps the hashed-filename problem: a content-hashed name can't be known before the compile, so any "resolve to final chunk URL" API would otherwise have to force the compile at SSR time.
2. A server-side resolve API (resolveModuleUrl(id) or similar) that triggers/awaits compilation of the lazy entry and returns the served URL(s). The SSR render knows exactly which dynamic modules it rendered, so it would only warm those — the deferral still pays off for everything unrendered. Slightly worse than (1) because it serializes compile into the render, but entirely workable.

One extra wrinkle worth noting for either shape: ideally the answer includes the entry's static import chain too (the chunks the entry will pull in), so the preload hints are complete — that's what we read from manifest.json in prod. But entry-URL-only would already unblock correctness; the import chain is the optimization layer on top.

Happy to prototype against a branch if you land on a direction.

[nihgwu]

We’ve now hit another instance of this API gap while testing @vitejs/plugin-rsc with experimental.bundledDev in a real application.

RSC SSR discovers CSS imports from route-specific and server-rendered modules. In normal dev mode, those module IDs can be emitted as stylesheet URLs in the rendered HTML. With bundledDev, the normal transform middleware is unavailable and environment.bundledDev.memoryFiles contains only bundle outputs, so the RSC integration cannot safely translate a discovered CSS module ID into a browser-loadable URL.

This appears to require the same general primitive proposed here: an environment-aware way to map a module ID to its current served bundled output URL. For CSS, the result must be directly loadable as a stylesheet, rather than the JavaScript wrapper produced by the normal development CSS transform.

The plugin should not need to parse generated chunks, create data URLs, or install custom CSS middleware. A Vite-owned mapping or direct transformation API would allow RSC and other SSR integrations to emit correct preload and stylesheet links while preserving bundledDev’s ownership of its generated output.

[sapphi-red]

Thanks for the explanations.

While I'm still thinking about the design, I have a question. Did you wait for the client bundle to be ready? Was that possible? I assume that is needed to properly reference the client output from SSR, otherwise it may return 404.

[ryansolid]

Good question — timing wasn't the failure mode we hit, though it's entangled with the design.

We didn't add an explicit wait on the client bundle, and waiting wouldn't have changed the outcome: our dev asset resolver derives URLs purely from module ids (/src/routes/(basic).tsx?pick=default&pick=$css) and never reads anything the client build produces, so a fully completed bundle leaves the emitted HTML byte-identical — and those module-id URLs are never servable in bundled dev, since memoryFilesMiddleware only answers for output fileNames and there's no way to learn which output file corresponds to a module id. The 404s persist at every point in the build lifecycle. It's a mapping gap, not a race. (Our only bundled-dev accommodation is the hardcoded entry-chunk name described under "Alternative" above — the entry loads fine; it's the code-split modules that have no equivalent.)

That said, you're right that a real solution has an await in it, in two distinct senses:

1. Initial build: an id→URL API would need waitForInitialBuildFinish-like semantics for modules in the initial client graph — that's what we meant in the proposal. Fine for SSR: streaming renders already await async work mid-stream.
2. Lazy-bundled entries are the harder case: our code-split routes are exactly the deferred entries, so they aren't in the initial build at all — there's nothing to wait for until something triggers compileEntry, and today the only trigger requires a live HMR clientId, which doesn't exist during the first SSR render. That's why the facade-URL shape appeals to us: a stable, unhashed URL per deferred entry whose first browser request is the compile trigger means SSR never blocks on a compile and never needs the bundle graph — and lazy bundling keeps full deferral. The resolve-API shape works too if it can trigger/await lazy compilation without a clientId; it just serializes that compile into the render.

So: "wait for the client bundle" is answerable and workable for the initial graph, impossible today for lazy entries — and either way the missing primitive is the id→URL mapping.