feat(vite-plugin): RSC build manifest for deploy

[agcty]

Status / stack

Draft until #47 lands or maintainers confirm this should be reviewed before that merge.

• Depends on feat(vite-plugin): RSC dev support via viteEnvironment child environments #47 for the viteEnvironment child-environment model.
• GitHub shows feat(vite-plugin): RSC dev support via viteEnvironment child environments #47's commits in this PR because both branches come from a fork and the PR must target upstream main.
• Review the build-specific delta here: agcty/cloudflare-tools feat/rsc-dev...feat/rsc-build.
• Downstream consumer: feat(cloudflare): consume distilled Vite manifests alchemy#615 consumes this manifest from Cloudflare.Vite and has now been live-tested with a one-worker Vite + Durable Object fixture.

What

Adds the production-build half of RSC support to the distilled Cloudflare vite plugin. A vite build now emits a __distilled-build.json manifest describing the deployable Worker - its entry, full module set, compatibility data, module types, and static-assets directory - so a deployer such as Alchemy's Cloudflare.Vite can ship an RSC app without inferring the topology from directory convention or a single environment's in-memory bundle.

Dev support is #47. This PR is the build/deploy contract. The deploy-side consumer is alchemy-run/alchemy#615.

Why an explicit manifest, and why on disk

The official @cloudflare/vite-plugin does not infer the Worker from directory convention either: it writes an explicit deploy contract to disk (.wrangler/deploy/config.json plus per-worker Wrangler config) that Wrangler reads. This PR follows the same pattern, but emits a Wrangler-free, deployer-native manifest - keeping the information a deployer needs while avoiding a Wrangler-specific format.

On disk, specifically:

• The worker bundles are already on disk - vite build writes dist/server/**, dist/ssr/**, dist/client/**, etc.
• The manifest is a small index pointing at those files. A plain vite build produces it, it is inspectable, and it does not couple the consumer to plugin internals. Because Alchemy runs the build in-process it could capture the manifest object in memory, but it still has to read the module bundles from disk, so an on-disk manifest is the natural CLI-compatible contract.

The single-worker module set

The official plugin can model rsc -> ssr as multiple Workers with service bindings. The distilled plugin's RSC topology currently folds this into one uploaded Worker module set: the worker entry loads child-environment output through module imports, so the deployed Worker is a single Worker whose module set spans the entry (rsc) plus child (ssr) outputs. The manifest preserves the on-disk relative layout so those cross-environment imports resolve after upload.

That matches the current distilled runtime model and the Alchemy consumer in #615. Multi-worker/service-binding topology is a future manifest extension, not part of this PR.

The manifest

Current v2 shape:

{
  "version": 2,
  "workers": {
    "app": {
      "main": "server/entry.worker.js",
      "modules": [
        { "path": "server/entry.worker.js", "type": "esm" },
        { "path": "ssr/index.js", "type": "esm" },
        { "path": "ssr/assets-manifest.json", "type": "json" }
      ],
      "compatibilityDate": "2026-03-17",
      "compatibilityFlags": ["nodejs_compat"]
    }
  },
  "assets": {
    "directory": "client",
    "runWorkerFirst": ["/api/*"]
  }
}

All paths are POSIX-style and relative to the manifest directory (the build root). main is the distilled worker-entry chunk, identified by its module marker, so it is not confused with a framework's own entry. Module kind is explicit (esm, wasm, data, text, json) using the same module rules the build emits.

A deployer reads the manifest, uploads workers.app.modules as one module set with workers.app.main as the entry, and serves assets.directory with the optional asset-routing settings.

buildApp: defer to the framework

The plugin previously imposed its own buildApp loop, which double-built every environment on top of plugin-rsc's multi-pass orchestration. It now defers to the framework's buildApp and writes the manifest in a buildApp hook with order: "post", after every environment is on disk - the same broad timing hook the official plugin uses.

Edge cases handled by design

• Asset/route ignoring - the manifest lives beside the build root, not in client, so it is not served as a client asset.
• Stale output - worker output dirs are emptied up front so the on-disk module set reflects only the current build.
• Stale manifest - a build that emits no manifest (SPA/assets-only, or a refused split output layout) removes any prior manifest.
• Module kinds - the module set covers all Cloudflare module kinds via explicit manifest tags, not just JS/Wasm.
• Scan passes - entry capture skips non-writing scan passes and records the real worker entry.

Verified

Across both RSC fixtures and a non-RSC worker fixture:

• An AST-accurate scan (Bun.Transpiler) confirms every relative import in the worker module set resolves within the set and no client assets leak in.
• main is always the real worker entry.
• A pure SPA (static-website) emits no manifest and removes any stale prior manifest.
• Build-mode tests lock the contract, including stale-output/stale-manifest handling.
• format / lint / typecheck are clean.

Downstream validation in alchemy-run/alchemy#615:

• Cloudflare.Vite reads this v2 manifest and uploads the manifest-selected module set with explicit content types.
• A live Cloudflare deploy test passed for one Vite Worker with a local Durable Object binding: static assets served, /api/reset returned ok, and /api/count incremented through the DO.
• alchemy dev also served the same fixture locally through the distilled runtime and Vite dev server.

Limitations & follow-ups

• Custom build.outDir with the RSC topology is unsupported. plugin-rsc keeps the ssr child at dist/ssr even when the entry moves, so the worker output spans two roots. The plugin detects this, emits nothing, and removes any stale manifest rather than producing a broken one.
• The manifest currently models the distilled single-worker topology. Multi-worker/service-binding topology can be added later by extending workers beyond workers.app after a deployer needs that shape.
• Sourcemap upload signaling and export-shape hints are possible future additions. Bindings, secrets, migrations, and resource ownership remain deploy-time inputs, not build outputs.

Scope

• feat(vite-plugin): RSC dev support via viteEnvironment child environments #47 - RSC dev support.
• This PR - RSC build support: the deploy manifest plus buildApp deferral.
• feat(cloudflare): consume distilled Vite manifests alchemy#615 - deploy-side consumer of this manifest.

---

Written on behalf of agcty.

[john-royal]

Replaced by #55. I adapted a lot of your work so you're listed as a co-author.