Add support for child environments

[jamesopstad]

Add support for child environments.

This is to support React Server Components via @vitejs/plugin-rsc and frameworks that build on top of it. A childEnvironments option is now added to the plugin config to enable using multiple environments within a single Worker. The parent environment can import modules from a child environment in order to access a separate module graph. For a typical RSC use case, the plugin might be configured as in the following example:

export default defineConfig({
	plugins: [
		cloudflare({
			viteEnvironment: {
				name: "rsc",
				childEnvironments: ["ssr"],
			},
		}),
	],
});

Notes

This is implemented to support the convention defined in vitejs/vite-plugin-react#1037. I have manually tested that it works with @vitejs/plugin-rsc.

I have omitted adding built in build functionality for child environments as it should be handled by another plugin e.g. @vitejs/plugin-rsc or the framework.

• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because:
• Public documentation
  • Cloudflare docs PR(s): Add childEnvironments to Vite plugin API docs cloudflare-docs#27631
  • Documentation not necessary because:

A picture of a cute animal (not mandatory, but encouraged)

---

[changeset-bot]

🦋 Changeset detected

Latest commit: f09f21f

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

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

[pkg-pr-new]

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@11879

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@11879

miniflare

npm i https://pkg.pr.new/miniflare@11879

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@11879

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@11879

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@11879

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@11879

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@11879

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@11879

wrangler

npm i https://pkg.pr.new/wrangler@11879

commit: f09f21f

[petebacondarwin]

Just for fun I tried out the new PR review feature in Devin: https://app.devin.ai/review/cloudflare/workers-sdk/pull/11879

[devin-ai-integration]

🟡 Missing validation for child environment name collisions

In plugin-config.ts, there is validation that parent worker environment names don't collide with each other (line 380-383), but there is no validation that:

1. A child environment name doesn't collide with a parent environment name
2. A child environment name doesn't collide with another child environment name (from same or different parent)
3. A child environment name doesn't collide with "client" (the reserved environment name)

In getEnvironmentsConfig (config.ts:155-197), child environments are added to workerEnvironments via Object.fromEntries. If there's a collision, the later entry silently overwrites the earlier one.

For example, if a user configures:

cloudflare({
  viteEnvironment: {
    name: "parent",
    childEnvironments: ["parent"], // Overwrites parent!
  }
})

Or:

cloudflare({
  viteEnvironment: {
    name: "parent",
    childEnvironments: ["client"], // Gets overwritten by client config!
  }
})

This would lead to silent misconfiguration and unexpected runtime behavior.

Recommendation: Add validation after setting child environments to ensure no child environment name collides with any parent environment name, other child environment names, or the reserved "client" name. This could be done by collecting all environment names and checking for duplicates before returning the resolved config.

🛟 Review with Devin

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[petebacondarwin]

It's late here and my brain is not working at 100%.
But I read through all the code and it makes sense to me.
Moreover the playground tests appear to pass!
I assume you have tried this out with a real RSC project outside of the PR?
Devin picked up on a potential validation improvement but I don't think that should block my approval.
Nice work @jamesopstad.

[jamesopstad]

It's late here and my brain is not working at 100%. But I read through all the code and it makes sense to me. Moreover the playground tests appear to pass! I assume you have tried this out with a real RSC project outside of the PR? Devin picked up on a potential validation improvement but I don't think that should block my approval. Nice work @jamesopstad.

Thanks for the review @petebacondarwin! The Devin comment is valid but I'll add the validation in a follow up PR so that it doesn't block things now. I've confirmed this works in real RSC projects using @vitejs/plugin-rsc.