fix(vite-plugin-cloudflare): add hot channel api for ssrLoadModule compatibility

[hyf0]

Summary

CloudflareDevEnvironment's hot channel is missing the api property (innerEmitter / outsideEmitter), which causes server.ssrLoadModule() to crash when called by other Vite plugins on a dev server where @cloudflare/vite-plugin is active:

TypeError: Cannot read properties of undefined (reading 'outsideEmitter')
    at Object.connect (createServerModuleRunnerTransport)
    at new SSRCompatModuleRunner
    at ssrLoadModule

Root cause

ssrLoadModule() creates an SSRCompatModuleRunner whose transport accesses environment.hot.api.outsideEmitter. Vite's built-in createServerHotChannel() (used by RunnableDevEnvironment) provides this api property, but CloudflareDevEnvironment's createHotChannel() does not.

The HotChannel interface defines api as optional (api?: Api), but createServerModuleRunnerTransport unconditionally accesses it.

Fix

Add api: { innerEmitter, outsideEmitter } to createHotChannel(), matching what createServerHotChannel() provides. This makes CloudflareDevEnvironment compatible with ssrLoadModule() without changing its existing WebSocket-based module execution.

Use case

Framework plugins that perform SSG/prerendering call server.ssrLoadModule() during build to execute exports from page files (e.g. collecting prerender paths for static site generation). When @cloudflare/vite-plugin is present in the user's config, this crashes because the SSR environment is a CloudflareDevEnvironment with an incomplete hot channel.

Related

• ssrLoadModule() crashes with FetchableDevEnvironment (outsideEmitter undefined) vitejs/vite#21726 — original issue report
• fix(ssr): throw friendly error when calling ssrLoadModule with non-runnable ssr env vitejs/vite#21739 — Vite PR to improve the error message (confirms ssrLoadModule requires a runnable environment, but the hot channel api gap is on the plugin side)

[changeset-bot]

⚠️ No Changeset found

Latest commit: dc09362

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[workers-devprod]

Codeowners approval required for this PR:

• @cloudflare/wrangler

Show detailed file reviewers

• packages/vite-plugin-cloudflare/src/cloudflare-environment.ts: [@cloudflare/wrangler]

[Copilot]

Pull request overview

This PR fixes a compatibility gap between @cloudflare/vite-plugin’s dev environment and Vite’s server.ssrLoadModule() by aligning CloudflareDevEnvironment’s hot channel with what Vite’s server-side module runner expects.

Changes:

• Add hot.api to the Cloudflare hot channel (innerEmitter / outsideEmitter) to match Vite’s server hot channel shape.
• Emit outsideEmitter "send" events when sending payloads, and emit innerEmitter "connection" when the channel starts listening.
• Clean up emitter listeners on hot channel close().

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.

[hyf0]

Closing — adding api to the hot channel prevents the crash but doesn't make ssrLoadModule actually work, since CloudflareDevEnvironment still requires a running Miniflare backend to execute modules. The transport times out waiting for a worker that was never started. The fix belongs on the caller's side (overriding createEnvironment to use createRunnableDevEnvironment).