Adds a modes field to cloudflare.config.ts, so per-environment config can be declared statically instead of computed at runtime.

Why

Under --x-new-config the only way to vary config per environment is to branch on ctx.mode inside the function form of a config:

export default defineWorker((ctx) => ({
	name: ctx.mode === "production" ? "my-worker-prod" : "my-worker",
	env: ctx.mode === "production" ? { API_KEY: bindings.secret() } : {},
}));

That is fine at runtime, but wrangler types cannot see through it. generateTypes emits UnwrapConfig<typeof import("./cloudflare.config").default>, and defineWorker infers its type parameter from the function's return type, so every branch collapses into one. A binding that only exists in production ends up indistinguishable from one that always exists.

The result is that the new config format has no equivalent of the per-environment type aggregation the Wrangler JSON config gets from env.*. This is also the thing that makes it awkward to split a large config into several files: composition itself already works through ordinary import statements, since cloudflare.config.ts is a real TypeScript module and load.ts already tracks transitive imports for reload. It was only the types that did not keep up.

What this adds

export default defineWorker({
	name: "my-worker",
	compatibilityDate: "2026-06-01",
	env: { SHARED_KV: bindings.kv({ id: "..." }) },
	modes: {
		staging: { env: { API_KEY: bindings.secret() } },
		production: {
			name: "my-worker-prod",
			env: { API_KEY: bindings.secret(), ANALYTICS: bindings.r2({ name: "..." }) },
		},
	},
});

Each entry is a partial Worker config layered over the base when that mode is selected with --env or CLOUDFLARE_ENV. env and exports merge per key, so a mode only states what differs. Every other field replaces the base value outright, which means an inherited array can always be dropped rather than being stuck with it.

Because the modes are declared rather than computed, wrangler types can aggregate them:

• a binding every mode declares is required on Env
• a binding only some declare is optional
• its type is the union of the types the declaring modes give it

which is the same rule generatePerEnvironmentTypes already applies to env.* for the JSON config. Each mode's exact env is available as Cloudflare.EnvFor<"production">, and the declared names as Cloudflare.Mode.

Implementation notes

• The merge lives in loadAndValidateConfig, the single choke point both Wrangler and the Vite plugin load through, so neither needed a change beyond error mapping.
• It runs after schema validation, so a bad binding inside a mode reports against modes.production.env.FOO rather than a merged path the user never wrote.
• modes is stripped from the result, so nothing downstream of config loading knows the feature exists. It never reaches OutputWorkerSchema or convertToWranglerConfig.
• Type aggregation is done with type level helpers over typeof import(...) rather than by emitting concrete literal types. That keeps the existing property that generated types resolve from source and cannot go stale.
• A config that declares no modes is passed through untouched whatever the mode is. Branching on ctx.mode is still valid and still works, so this is purely additive.

Verification

Beyond the unit tests, I generated a worker-configuration.d.ts from a config that splits its bindings across two files and type checked a Worker against it. The positive cases pass and the negative cases fail with the errors you would want:

negative.ts(3,2): error TS2322: Type 'R2Bucket | undefined' is not assignable to type 'R2Bucket'.
negative.ts(6,14): error TS2322: Type '"dev"' is not assignable to type '"staging" | "production"'.
negative.ts(9,13): error TS2339: Property 'ANALYTICS' does not exist on type '{ SHARED_KV: KVNamespace<string>; readonly API_KEY: string; }'.

• 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):
  • Documentation not necessary because: this extends --x-new-config, which is experimental and opt-in and not yet covered in the public docs. Docs for the config format, including modes, should land together when the feature stabilises.