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 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