Programmatic configuration

The Wrangler configuration file is optional when using the Cloudflare Vite plugin. Without one, the plugin uses default values. You can customize Worker configuration programmatically with the config option. This is useful when the Cloudflare plugin runs inside another plugin or framework.

Note

Programmatic configuration is primarily designed for use by frameworks and plugin developers. Users should normally use Wrangler config files instead. Configuration set via the config option will not be included when running wrangler types or resource based Wrangler CLI commands such as wrangler kv or wrangler d1.

Default configuration

Without a configuration file, the plugin generates sensible defaults for an assets-only Worker. The name comes from package.json or the project directory name. The compatibility_date uses the latest date supported by your installed Miniflare version.

The `config` option

The config option offers three ways to programmatically configure your Worker. You can set any property from the Wrangler configuration file, though some options are ignored or replaced by Vite equivalents.

Note

You cannot define Cloudflare environments via config, as they are resolved before this option is applied.

Configuration object

Set config to an object to provide values that merge with defaults and Wrangler config file settings:

vite.config.ts

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	plugins: [
		cloudflare({
			config: {
				compatibility_date: "2025-01-01",
				vars: {
					API_URL: "https://api.example.com",
				},
			},
		}),
	],
});

These values merge with Wrangler config file values, with the config values taking precedence.

Dynamic configuration function

Use a function when configuration depends on existing config values or external data, or if you need to compute or conditionally set values:

vite.config.ts

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	plugins: [
		cloudflare({
			config: (userConfig) => ({
				vars: {
					WORKER_NAME: userConfig.name,
					BUILD_TIME: new Date().toISOString(),
				},
			}),
		}),
	],
});

The function receives the current configuration (defaults or loaded config file). Return an object with values to merge.

In-place editing

A config function can mutate the config object directly instead of returning overrides. This is useful for deleting properties or removing array items:

vite.config.ts

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	plugins: [
		cloudflare({
			config: (userConfig) => {
				// Replace all existing compatibility flags
				userConfig.compatibility_flags = ["nodejs_compat"];
			},
		}),
	],
});

Note

When editing in place, do not return a value from the function.

Auxiliary Workers

Auxiliary Workers also support the config option, enabling multi-Worker architectures without config files.

Define auxiliary Workers without config files using config inside the auxiliaryWorkers array:

vite.config.ts

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	plugins: [
		cloudflare({
			config: {
				name: "entry-worker",
				main: "./src/entry.ts",
				compatibility_date: "2025-01-01",
				services: [{ binding: "API", service: "api-worker" }],
			},
			auxiliaryWorkers: [
				{
					config: {
						name: "api-worker",
						main: "./src/api.ts",
						compatibility_date: "2025-01-01",
					},
				},
			],
		}),
	],
});

Configuration overrides

Combine a config file with config to override specific values:

vite.config.ts

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	plugins: [
		cloudflare({
			configPath: "./wrangler.jsonc",
			auxiliaryWorkers: [
				{
					configPath: "./workers/api/wrangler.jsonc",
					config: {
						vars: {
							ENDPOINT: "https://api.example.com/v2",
						},
					},
				},
			],
		}),
	],
});

Configuration inheritance

Auxiliary Workers receive the resolved entry Worker config in the second parameter to the config function. This makes it straightforward to inherit configuration from the entry Worker in auxiliary Workers.

vite.config.ts

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	plugins: [
		cloudflare({
			auxiliaryWorkers: [
				{
					config: (_, { entryWorkerConfig }) => ({
						name: "auxiliary-worker",
						main: "./src/auxiliary-worker.ts",
						// Inherit compatibility settings from entry Worker
						compatibility_date: entryWorkerConfig.compatibility_date,
						compatibility_flags: entryWorkerConfig.compatibility_flags,
					}),
				},
			],
		}),
	],
});

Configuration merging behavior

The config option uses defu for merging configuration objects.

Object properties are recursively merged
Arrays are concatenated (config values first, then existing values)
Primitive values from config override existing values
undefined values in config do not override existing values

Default configuration

The config option

Configuration object

Dynamic configuration function

In-place editing

Auxiliary Workers

Configuration overrides

Configuration inheritance

Configuration merging behavior

The `config` option