Add per-Worker devOnly property to the plugin config

[jamesopstad]

Replacement for #12788 that makes opting in explicit. This means it doesn't break compatibility with existing framework integrations.

Add per-Worker devOnly option to the plugin config

This determines if the given Worker should be built. It accepts a boolean or a function that returns a boolean. The function is evaluated lazily at build time, allowing frameworks to provide the value after initialization.

export default defineConfig({
	plugins: [
		cloudflare({
			auxiliaryWorkers: [
				{ configPath: "./dev-only-worker/wrangler.jsonc", devOnly: true },
			],
		}),
	],
});

Some frameworks, such as Astro, use the ssr environment during development but omit it from the build if the app is fully static. In these cases, we now output an assets only version of the user's input Wrangler config to the output config in the client output directory.

---

• 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 devOnly option to Vite plugin API reference cloudflare-docs#31016
  • Documentation not necessary because:

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 2dfbb39

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

This PR includes changesets to release 1 package

Name	Type
@cloudflare/vite-plugin	Minor

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

[github-actions]

✅ All changesets look good

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds a devOnly property to the vite-plugin-cloudflare config, allowing Workers to be excluded from production builds while remaining available during development. The implementation correctly handles filtering in buildApp, writeDeployConfig, and the output config plugin, with no double-write scenarios.

Issue found:

1. Mislabeled describe block (prerendering.spec.ts:9): The describe block is labeled "no-ssr" but this is the default config where SSR is active (the test asserts status 200). The label was likely copy-pasted from no-ssr/prerendering.spec.ts. Posted a suggestion to rename it to "with-ssr".

github run

[pkg-pr-new]

create-cloudflare

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

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-pool-workers

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

@cloudflare/workers-editor-shared

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

@cloudflare/workers-utils

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

wrangler

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

commit: 2dfbb39

[workers-devprod]

Codeowners approval required for this PR:

• ✅ @cloudflare/wrangler

Show detailed file reviewers

[devin-ai-integration]

Devin Review found 1 potential issue.

View 4 additional findings in Devin Review.

[devin-ai-integration]

🟡 Missing directory creation before writing wrangler.json for devOnly entry worker

In config.ts's buildApp handler, when the entry worker is devOnly (not built), the code writes wrangler.json directly to the client output directory using fs.writeFileSync without first ensuring the directory exists. The client output directory is only created by Vite when the client environment is actually built. In build.ts:50-60, createBuildApp only builds the client if hasClientEntry, getHasPublicAssets, or prerenderWorkerEnvironmentName is truthy. If none of these conditions hold (e.g., a devOnly entry worker with no index.html, no public assets, and no prerender worker), the client directory won't exist and fs.writeFileSync will throw an ENOENT error.

Suggested change

	fs.writeFileSync(
	path.resolve(
	builder.config.root,
	clientEnvironment.config.build.outDir,
	"wrangler.json"
	),
	JSON.stringify(outputConfig)
	);
	const wranglerJsonPath = path.resolve(
	builder.config.root,
	clientEnvironment.config.build.outDir,
	"wrangler.json"
	);
	fs.mkdirSync(path.dirname(wranglerJsonPath), { recursive: true });
	fs.writeFileSync(wranglerJsonPath, JSON.stringify(outputConfig));

---

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

[ascorbic]

Nice!

[workers-devprod]

Codeowners reviews satisfied

[edmundhung]

Nit: Bike-shedding the name a bit as I find devOnly confusing 😄

How about build: false or skipBuild: true?