Add assetsOnly/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 assetsOnly (entry Worker) and devOnly (auxiliary Workers) options to the plugin config

Both options accept 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.

Use assetsOnly on the entry Worker to skip building the Worker and instead emit an assets-only Wrangler config to the client output directory. This enables frameworks such as Astro to use the ssr environment during development but produce a fully static app for deployment.

export default defineConfig({
	plugins: [
		cloudflare({
			assetsOnly: () => isStaticBuild,
		}),
	],
});

Use devOnly on an auxiliary Worker to include it during vite dev but skip it at build time.

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

---

• 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: a690998

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/cloudflare/workers-sdk/create-cloudflare@13985

@cloudflare/deploy-helpers

npm i https://pkg.pr.new/cloudflare/workers-sdk/@cloudflare/deploy-helpers@13985

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-pool-workers

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

@cloudflare/workers-editor-shared

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

@cloudflare/workers-utils

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

wrangler

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

commit: a690998

[workers-devprod]

Codeowners approval required for this PR:

• ✅ @cloudflare/wrangler

Show detailed file reviewers

[ascorbic]

Nice!

[workers-devprod]

Codeowners reviews satisfied

[jamesopstad]

@edmundhung I've renamed the option to assetsOnly on the entry Worker, which better reflects what it does.

Outputting the assets-only config and modified deploy config when the entry Worker is built would be breaking with the current setup, because in TanStack Start the modified deploy config would break pre-rendering. I plan to do a follow up PR once this one's released that doesn't read the deploy config during pre-rendering. Best to do that in a separate PR as it's a more risky change. Please take another look.

[edmundhung]

It looks like you keep checking whether environment is built for now. Is that you plan to fix it all together with the prerendering issue you mentioned?

I am still unsure about the usecase of devOnly in auxiliary workers, but definitely not a blocking concern.

Feel free to merge :)