From ef2a04221b9e44ebd6d36993ebe9e53ac3a60ace Mon Sep 17 00:00:00 2001 From: Matt Kane Date: Fri, 28 Nov 2025 17:46:23 +0000 Subject: [PATCH 1/7] [Vite plugin]: add programmatic worker config --- .../workers/vite-plugin/reference/api.mdx | 23 ++- .../reference/programmatic-configuration.mdx | 158 ++++++++++++++++++ 2 files changed, 179 insertions(+), 2 deletions(-) create mode 100644 src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx diff --git a/src/content/docs/workers/vite-plugin/reference/api.mdx b/src/content/docs/workers/vite-plugin/reference/api.mdx index cde4a5e711903eb..04b3a859bd0e7d2 100644 --- a/src/content/docs/workers/vite-plugin/reference/api.mdx +++ b/src/content/docs/workers/vite-plugin/reference/api.mdx @@ -32,6 +32,15 @@ It accepts an optional `PluginConfig` parameter. For more information about the Worker configuration, see [Configuration](/workers/wrangler/configuration/). +- `configure` + + Customize or override Worker configuration programmatically. + Accepts a partial configuration object or a function that receives the current config. + + Applied after any config file loads. Use it to override values, or define Workers entirely in code. + + See [Programmatic configuration](/workers/vite-plugin/reference/programmatic-configuration/) for details. + - `viteEnvironment` Optional Vite environment options. @@ -75,12 +84,22 @@ It accepts an optional `PluginConfig` parameter. ## `interface AuxiliaryWorkerConfig` -- `configPath` +Auxiliary Workers require a `configPath`, a `configure` option, or both. - A required path to your Worker config file. +- `configPath` + + The path to your Worker config file. + This field is required unless `configure` is provided. For more information about the Worker configuration, see [Configuration](/workers/wrangler/configuration/). +- `configure` + + Customize or override Worker configuration programmatically. + When used without `configPath`, this allows defining auxiliary Workers entirely in code. + + See [Programmatic configuration](/workers/vite-plugin/reference/programmatic-configuration/) for usage examples. + - `viteEnvironment` Optional Vite environment options. diff --git a/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx b/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx new file mode 100644 index 000000000000000..9aab9d352e20650 --- /dev/null +++ b/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx @@ -0,0 +1,158 @@ +--- +pcx_content_type: reference +title: Programmatic configuration +sidebar: + order: 4 +description: Configure Workers programmatically using the Vite plugin +--- + +import { WranglerConfig } from "~/components"; + +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 `configure` option. This is useful when the Cloudflare plugin runs inside another plugin or framework. + +## 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 `configure` option + +The `configure` option offers three ways to programmatically configure your Worker: + +### Configuration object + +Set `configure` to an object to provide values that merge with defaults and config file settings: + +```ts title="vite.config.ts" +import { defineConfig } from "vite"; +import { cloudflare } from "@cloudflare/vite-plugin"; + +export default defineConfig({ + plugins: [ + cloudflare({ + configure: { + compatibility_date: "2025-01-01", + vars: { + API_URL: "https://api.example.com", + }, + }, + }), + ], +}); +``` + +These values merge with config file values. The `configure` values take precedence. + +### Dynamic configuration function + +Use a function when configuration depends on existing config values or external data: + +```ts title="vite.config.ts" +import { defineConfig } from "vite"; +import { cloudflare } from "@cloudflare/vite-plugin"; + +export default defineConfig({ + plugins: [ + cloudflare({ + configure: (config) => ({ + vars: { + WORKER_NAME: config.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 `configure` function can mutate the config object directly instead of returning overrides. This is useful for deleting properties or removing array items: + +```ts title="vite.config.ts" +import { defineConfig } from "vite"; +import { cloudflare } from "@cloudflare/vite-plugin"; + +export default defineConfig({ + plugins: [ + cloudflare({ + configure: (config) => { + // Replace all existing compatibility flags + config.compatibility_flags = ["nodejs_compat"]; + }, + }), + ], +}); +``` + +When editing in place, do not return a value from the function. + +## Auxiliary Workers + +Auxiliary Workers also support the `configure` option, enabling multi-Worker architectures without config files. + +Define auxiliary Workers without config files using `configure` inside the `auxiliaryWorkers` array: + +```ts title="vite.config.ts" +import { defineConfig } from "vite"; +import { cloudflare } from "@cloudflare/vite-plugin"; + +export default defineConfig({ + plugins: [ + cloudflare({ + configure: { + name: "entry-worker", + main: "./src/entry.ts", + compatibility_date: "2025-01-01", + services: [{ binding: "API", service: "api-worker" }], + }, + auxiliaryWorkers: [ + { + configure: { + name: "api-worker", + main: "./src/api.ts", + compatibility_date: "2025-01-01", + }, + }, + ], + }), + ], +}); +``` + +### Configuration overrides + +Combine a config file with `configure` to override specific values: + +```ts title="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", + configure: { + vars: { + ENDPOINT: "https://api.example.com/v2", + }, + }, + }, + ], + }), + ], +}); +``` + +## Configuration merging behavior + +The `configure` option uses [defu](https://github.com/unjs/defu) for merging configuration objects. + +- Object properties are recursively merged +- Arrays are concatenated (configure values first, then existing values) +- Primitive values from `configure` override existing values +- `undefined` values in `configure` do not override existing values From afa9d0fbdf429ef0c3315d363722abc913181f83 Mon Sep 17 00:00:00 2001 From: Matt Kane Date: Sat, 29 Nov 2025 11:34:00 +0000 Subject: [PATCH 2/7] Add changelog --- .../2025-12-02-vite-optional-config.mdx | 11 ++ .../2025-12-02-vite-programmatic-config.mdx | 106 ++++++++++++++++++ 2 files changed, 117 insertions(+) create mode 100644 src/content/changelog/workers/2025-12-02-vite-optional-config.mdx create mode 100644 src/content/changelog/workers/2025-12-02-vite-programmatic-config.mdx diff --git a/src/content/changelog/workers/2025-12-02-vite-optional-config.mdx b/src/content/changelog/workers/2025-12-02-vite-optional-config.mdx new file mode 100644 index 000000000000000..1ad27ae1e056280 --- /dev/null +++ b/src/content/changelog/workers/2025-12-02-vite-optional-config.mdx @@ -0,0 +1,11 @@ +--- +title: Wrangler config is optional when using Vite plugin +description: When using the Cloudflare Vite plugin in an assets-only (static) site, a Wrangler configuration file is now optional. +products: + - workers +date: 2025-12-02 +--- + +When using the [Cloudflare Vite plugin](/workers/vite-plugin/) to build and deploy Workers, a Wrangler configuration file is now optional for assets-only (static) sites. If no `wrangler.toml`, `wrangler.json`, or `wrangler.jsonc` file is found, the plugin generates sensible defaults for an assets-only site. The `name` is based on the `package.json` or the project directory name, and the `compatibility_date` uses the latest date supported by your installed Miniflare version. + +This allows easier setup for static sites and Vite-based single-page applications (SPAs) that do not require custom Worker configuration. \ No newline at end of file diff --git a/src/content/changelog/workers/2025-12-02-vite-programmatic-config.mdx b/src/content/changelog/workers/2025-12-02-vite-programmatic-config.mdx new file mode 100644 index 000000000000000..ecc1020d3d7cf74 --- /dev/null +++ b/src/content/changelog/workers/2025-12-02-vite-programmatic-config.mdx @@ -0,0 +1,106 @@ +--- +title: Configure Workers programmatically using the Vite plugin +description: The Cloudflare Vite plugic can now programmatically configure Workers without a Wrangler config file, or modify existing configuration. +products: + - workers +date: 2025-12-02 +--- + +The [Cloudflare Vite plugin](/workers/vite-plugin/) now supports programmatic configuration of Workers without a Wrangler configuration file. You can use the `configure` option to define Worker settings directly in your Vite configuration, or to modify existing configuration loaded from a Wrangler config file. This is particularly useful when integrating with other build tools or frameworks, as it allows them to control Worker configuration without needing users to manage a separate config file. + +## The `configure` option + +The Vite plugin's new `configure` option accepts either a partial configuration object or a function that receives the current configuration and returns overrides. This option is applied after any config file is loaded, allowing the plugin to override specific values or define Workers entirely in code. + +## Example usage + +Setting `configure` to an object to provide configuration values that merge with defaults and config file settings: + +```ts title="vite.config.ts" +import { defineConfig } from "vite"; +import { cloudflare } from "@cloudflare/vite-plugin"; + +export default defineConfig({ + plugins: [ + cloudflare({ + configure: { + name: "my-worker", + compatibility_flags: ["nodejs_compat"], + send_email: [ + { + name: "EMAIL", + }, + ], + }, + }), + ], +}); +``` + +Use a function to modify the existing configuration: + +```ts title="vite.config.ts" +import { defineConfig } from "vite"; +import { cloudflare } from "@cloudflare/vite-plugin"; +export default defineConfig({ + plugins: [ + cloudflare({ + configure: (config) => { + delete config.compatibility_flags; + }, + }), + ], +}); +``` + +Return an object with values to merge: + +```ts title="vite.config.ts" +import { defineConfig } from "vite"; +import { cloudflare } from "@cloudflare/vite-plugin"; + +export default defineConfig({ + plugins: [ + cloudflare({ + configure: (config) => { + if (!config.compatibility_flags.includes("no_nodejs_compat")) { + return { compatibility_flags: ["nodejs_compat"] }; + } + }, + }), + ], +}); +``` + +### Auxiliary Workers + +Auxiliary Workers also support the `configure` option, enabling multi-Worker architectures without config files. + +Define auxiliary Workers without config files using `configure` inside the `auxiliaryWorkers` array: + +```ts title="vite.config.ts" +import { defineConfig } from "vite"; +import { cloudflare } from "@cloudflare/vite-plugin"; + +export default defineConfig({ + plugins: [ + cloudflare({ + configure: { + name: "entry-worker", + main: "./src/entry.ts", + services: [{ binding: "API", service: "api-worker" }], + }, + auxiliaryWorkers: [ + { + configure: { + name: "api-worker", + main: "./src/api.ts", + }, + }, + ], + }), + ], +}); +``` + +For more details and examples, see [Programmatic configuration](/workers/vite-plugin/reference/programmatic-configuration/). \ No newline at end of file From e23f95566e93cae3df7487d97f797df906731cab Mon Sep 17 00:00:00 2001 From: Matt Kane Date: Mon, 1 Dec 2025 09:45:07 +0000 Subject: [PATCH 3/7] Change name of option --- .../2025-12-02-vite-programmatic-config.mdx | 28 +++++------ .../reference/programmatic-configuration.mdx | 46 ++++++++++--------- 2 files changed, 38 insertions(+), 36 deletions(-) diff --git a/src/content/changelog/workers/2025-12-02-vite-programmatic-config.mdx b/src/content/changelog/workers/2025-12-02-vite-programmatic-config.mdx index ecc1020d3d7cf74..d3d5f8577a32936 100644 --- a/src/content/changelog/workers/2025-12-02-vite-programmatic-config.mdx +++ b/src/content/changelog/workers/2025-12-02-vite-programmatic-config.mdx @@ -1,20 +1,20 @@ --- title: Configure Workers programmatically using the Vite plugin -description: The Cloudflare Vite plugic can now programmatically configure Workers without a Wrangler config file, or modify existing configuration. +description: The Cloudflare Vite plugin can now programmatically configure Workers without a Wrangler config file, or modify existing configuration. products: - workers date: 2025-12-02 --- -The [Cloudflare Vite plugin](/workers/vite-plugin/) now supports programmatic configuration of Workers without a Wrangler configuration file. You can use the `configure` option to define Worker settings directly in your Vite configuration, or to modify existing configuration loaded from a Wrangler config file. This is particularly useful when integrating with other build tools or frameworks, as it allows them to control Worker configuration without needing users to manage a separate config file. +The [Cloudflare Vite plugin](/workers/vite-plugin/) now supports programmatic configuration of Workers without a Wrangler configuration file. You can use the `config` option to define Worker settings directly in your Vite configuration, or to modify existing configuration loaded from a Wrangler config file. This is particularly useful when integrating with other build tools or frameworks, as it allows them to control Worker configuration without needing users to manage a separate config file. -## The `configure` option +## The `config` option -The Vite plugin's new `configure` option accepts either a partial configuration object or a function that receives the current configuration and returns overrides. This option is applied after any config file is loaded, allowing the plugin to override specific values or define Workers entirely in code. +The Vite plugin's new `config` option accepts either a partial configuration object or a function that receives the current configuration and returns overrides. This option is applied after any config file is loaded, allowing the plugin to override specific values or define Workers entirely in code. ## Example usage -Setting `configure` to an object to provide configuration values that merge with defaults and config file settings: +Setting `config` to an object to provide configuration values that merge with defaults and config file settings: ```ts title="vite.config.ts" import { defineConfig } from "vite"; @@ -23,7 +23,7 @@ import { cloudflare } from "@cloudflare/vite-plugin"; export default defineConfig({ plugins: [ cloudflare({ - configure: { + config: { name: "my-worker", compatibility_flags: ["nodejs_compat"], send_email: [ @@ -45,8 +45,8 @@ import { cloudflare } from "@cloudflare/vite-plugin"; export default defineConfig({ plugins: [ cloudflare({ - configure: (config) => { - delete config.compatibility_flags; + config: (userConfig) => { + delete userConfig.compatibility_flags; }, }), ], @@ -62,8 +62,8 @@ import { cloudflare } from "@cloudflare/vite-plugin"; export default defineConfig({ plugins: [ cloudflare({ - configure: (config) => { - if (!config.compatibility_flags.includes("no_nodejs_compat")) { + config: (userConfig) => { + if (!userConfig.compatibility_flags.includes("no_nodejs_compat")) { return { compatibility_flags: ["nodejs_compat"] }; } }, @@ -74,9 +74,9 @@ export default defineConfig({ ### Auxiliary Workers -Auxiliary Workers also support the `configure` option, enabling multi-Worker architectures without config files. +Auxiliary Workers also support the `config` option, enabling multi-Worker architectures without config files. -Define auxiliary Workers without config files using `configure` inside the `auxiliaryWorkers` array: +Define auxiliary Workers without config files using `config` inside the `auxiliaryWorkers` array: ```ts title="vite.config.ts" import { defineConfig } from "vite"; @@ -85,14 +85,14 @@ import { cloudflare } from "@cloudflare/vite-plugin"; export default defineConfig({ plugins: [ cloudflare({ - configure: { + config: { name: "entry-worker", main: "./src/entry.ts", services: [{ binding: "API", service: "api-worker" }], }, auxiliaryWorkers: [ { - configure: { + config: { name: "api-worker", main: "./src/api.ts", }, diff --git a/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx b/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx index 9aab9d352e20650..c060ee60c3bd35c 100644 --- a/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx +++ b/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx @@ -8,19 +8,19 @@ description: Configure Workers programmatically using the Vite plugin import { WranglerConfig } from "~/components"; -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 `configure` option. This is useful when the Cloudflare plugin runs inside another plugin or framework. +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. ## 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 `configure` option +## The `config` option -The `configure` option offers three ways to programmatically configure your Worker: +The `config` option offers three ways to programmatically configure your Worker: ### Configuration object -Set `configure` to an object to provide values that merge with defaults and config file settings: +Set `config` to an object to provide values that merge with defaults and Wrangler config file settings: ```ts title="vite.config.ts" import { defineConfig } from "vite"; @@ -29,7 +29,7 @@ import { cloudflare } from "@cloudflare/vite-plugin"; export default defineConfig({ plugins: [ cloudflare({ - configure: { + config: { compatibility_date: "2025-01-01", vars: { API_URL: "https://api.example.com", @@ -40,11 +40,11 @@ export default defineConfig({ }); ``` -These values merge with config file values. The `configure` values take precedence. +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: +Use a function when configuration depends on existing config values or external data, or if you need to compute or conditionally set values: ```ts title="vite.config.ts" import { defineConfig } from "vite"; @@ -53,9 +53,9 @@ import { cloudflare } from "@cloudflare/vite-plugin"; export default defineConfig({ plugins: [ cloudflare({ - configure: (config) => ({ + config: (userConfig) => ({ vars: { - WORKER_NAME: config.name, + WORKER_NAME: userConfig.name, BUILD_TIME: new Date().toISOString(), }, }), @@ -68,7 +68,7 @@ The function receives the current configuration (defaults or loaded config file) ### In-place editing -A `configure` function can mutate the config object directly instead of returning overrides. This is useful for deleting properties or removing array items: +A `config` function can mutate the config object directly instead of returning overrides. This is useful for deleting properties or removing array items: ```ts title="vite.config.ts" import { defineConfig } from "vite"; @@ -77,22 +77,24 @@ import { cloudflare } from "@cloudflare/vite-plugin"; export default defineConfig({ plugins: [ cloudflare({ - configure: (config) => { + config: (userConfig) => { // Replace all existing compatibility flags - config.compatibility_flags = ["nodejs_compat"]; + 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 `configure` option, enabling multi-Worker architectures without config files. +Auxiliary Workers also support the `config` option, enabling multi-Worker architectures without config files. -Define auxiliary Workers without config files using `configure` inside the `auxiliaryWorkers` array: +Define auxiliary Workers without config files using `config` inside the `auxiliaryWorkers` array: ```ts title="vite.config.ts" import { defineConfig } from "vite"; @@ -101,7 +103,7 @@ import { cloudflare } from "@cloudflare/vite-plugin"; export default defineConfig({ plugins: [ cloudflare({ - configure: { + config: { name: "entry-worker", main: "./src/entry.ts", compatibility_date: "2025-01-01", @@ -109,7 +111,7 @@ export default defineConfig({ }, auxiliaryWorkers: [ { - configure: { + config: { name: "api-worker", main: "./src/api.ts", compatibility_date: "2025-01-01", @@ -123,7 +125,7 @@ export default defineConfig({ ### Configuration overrides -Combine a config file with `configure` to override specific values: +Combine a config file with `config` to override specific values: ```ts title="vite.config.ts" import { defineConfig } from "vite"; @@ -136,7 +138,7 @@ export default defineConfig({ auxiliaryWorkers: [ { configPath: "./workers/api/wrangler.jsonc", - configure: { + config: { vars: { ENDPOINT: "https://api.example.com/v2", }, @@ -150,9 +152,9 @@ export default defineConfig({ ## Configuration merging behavior -The `configure` option uses [defu](https://github.com/unjs/defu) for merging configuration objects. +The `config` option uses [defu](https://github.com/unjs/defu) for merging configuration objects. - Object properties are recursively merged -- Arrays are concatenated (configure values first, then existing values) -- Primitive values from `configure` override existing values -- `undefined` values in `configure` do not override existing values +- 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 From 6e798b068d4e48c9240ea203701a0b649657ce14 Mon Sep 17 00:00:00 2001 From: Matt Kane Date: Mon, 1 Dec 2025 11:06:19 +0000 Subject: [PATCH 4/7] Document config values unsupported by Vite --- .../reference/migrating-from-wrangler-dev.mdx | 29 ++++++++++++++++++- .../reference/programmatic-configuration.mdx | 6 +++- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/src/content/docs/workers/vite-plugin/reference/migrating-from-wrangler-dev.mdx b/src/content/docs/workers/vite-plugin/reference/migrating-from-wrangler-dev.mdx index 1115214db471bd4..a6367e23a3d8df6 100644 --- a/src/content/docs/workers/vite-plugin/reference/migrating-from-wrangler-dev.mdx +++ b/src/content/docs/workers/vite-plugin/reference/migrating-from-wrangler-dev.mdx @@ -25,5 +25,32 @@ Running `wrangler deploy --env some-env` is therefore not applicable and the env There are various options in the [Worker config file](/workers/wrangler/configuration/) that are ignored when using Vite, as they are either no longer applicable or are replaced by Vite equivalents. If these options are provided, then warnings will be printed to the console with suggestions for how to proceed. -Examples where the Vite configuration should be used instead include `alias` and `define`. + +### Not applicable + +The following build-related options are handled by Vite and are not applicable when using the Cloudflare Vite plugin: + +- `tsconfig` +- `rules` +- `build` +- `no_bundle` +- `find_additional_modules` +- `base_dir` +- `preserve_file_names` + +### Not supported + +- `site` — Use [Workers Assets](/workers/static-assets/) instead. + +### Replaced by Vite equivalents + +The following options have Vite equivalents that should be used instead: + +| Wrangler option | Vite equivalent | +| --- | --- | +| `define` | [`define`](https://vite.dev/config/shared-options.html#define) | +| `alias` | [`resolve.alias`](https://vite.dev/config/shared-options.html#resolve-alias) | +| `minify` | [`build.minify`](https://vite.dev/config/build-options.html#build-minify) | +| Local dev settings (`ip`, `port`, `local_protocol`, etc.) | [Server options](https://vite.dev/config/server-options.html) | + See [Vite Environments](/workers/vite-plugin/reference/vite-environments/) for more information about configuring your Worker environments in Vite. diff --git a/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx b/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx index c060ee60c3bd35c..863b395333abdcf 100644 --- a/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx +++ b/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx @@ -16,7 +16,11 @@ Without a configuration file, the plugin generates sensible defaults for an asse ## The `config` option -The `config` option offers three ways to programmatically configure your Worker: +The `config` option offers three ways to programmatically configure your Worker. You can set any property from the [Wrangler configuration file](/workers/wrangler/configuration/), though some options are [ignored or replaced by Vite equivalents](/workers/vite-plugin/reference/migrating-from-wrangler-dev/#redundant-fields-in-the-wrangler-config-file). + +:::note +You cannot define [Cloudflare environments](/workers/vite-plugin/reference/cloudflare-environments/) via `config`, as they are resolved before this option is applied. +::: ### Configuration object From 80298edd63bbdc2ea1afc44b2642290d703a8a3c Mon Sep 17 00:00:00 2001 From: Matt Kane Date: Mon, 1 Dec 2025 16:29:02 +0000 Subject: [PATCH 5/7] FIxes --- src/content/docs/workers/vite-plugin/reference/api.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/content/docs/workers/vite-plugin/reference/api.mdx b/src/content/docs/workers/vite-plugin/reference/api.mdx index 04b3a859bd0e7d2..f6a2eb9623c1070 100644 --- a/src/content/docs/workers/vite-plugin/reference/api.mdx +++ b/src/content/docs/workers/vite-plugin/reference/api.mdx @@ -32,12 +32,12 @@ It accepts an optional `PluginConfig` parameter. For more information about the Worker configuration, see [Configuration](/workers/wrangler/configuration/). -- `configure` +- `config` Customize or override Worker configuration programmatically. Accepts a partial configuration object or a function that receives the current config. - Applied after any config file loads. Use it to override values, or define Workers entirely in code. + Applied after any config file loads. Use it to override values, modify the existing config, or define Workers entirely in code. See [Programmatic configuration](/workers/vite-plugin/reference/programmatic-configuration/) for details. @@ -84,16 +84,16 @@ It accepts an optional `PluginConfig` parameter. ## `interface AuxiliaryWorkerConfig` -Auxiliary Workers require a `configPath`, a `configure` option, or both. +Auxiliary Workers require a `configPath`, a `config` option, or both. - `configPath` The path to your Worker config file. - This field is required unless `configure` is provided. + This field is required unless `config` is provided. For more information about the Worker configuration, see [Configuration](/workers/wrangler/configuration/). -- `configure` +- `config` Customize or override Worker configuration programmatically. When used without `configPath`, this allows defining auxiliary Workers entirely in code. From dcf3b40aa96dc16d0619220ded04ba2cf2702211 Mon Sep 17 00:00:00 2001 From: Matt Kane Date: Tue, 2 Dec 2025 14:15:15 +0000 Subject: [PATCH 6/7] Changes from review --- .../changelog/workers/2025-12-02-vite-optional-config.mdx | 2 +- .../changelog/workers/2025-12-02-vite-programmatic-config.mdx | 2 +- .../vite-plugin/reference/programmatic-configuration.mdx | 4 ++++ 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/src/content/changelog/workers/2025-12-02-vite-optional-config.mdx b/src/content/changelog/workers/2025-12-02-vite-optional-config.mdx index 1ad27ae1e056280..18b438587bfb131 100644 --- a/src/content/changelog/workers/2025-12-02-vite-optional-config.mdx +++ b/src/content/changelog/workers/2025-12-02-vite-optional-config.mdx @@ -8,4 +8,4 @@ date: 2025-12-02 When using the [Cloudflare Vite plugin](/workers/vite-plugin/) to build and deploy Workers, a Wrangler configuration file is now optional for assets-only (static) sites. If no `wrangler.toml`, `wrangler.json`, or `wrangler.jsonc` file is found, the plugin generates sensible defaults for an assets-only site. The `name` is based on the `package.json` or the project directory name, and the `compatibility_date` uses the latest date supported by your installed Miniflare version. -This allows easier setup for static sites and Vite-based single-page applications (SPAs) that do not require custom Worker configuration. \ No newline at end of file +This allows easier setup for static sites using Vite. Note that SPAs will still need to [set `assets.not_found_handling` to `single-page-application`](https://developers.cloudflare.com/workers/static-assets/routing/single-page-application/) in order to function correctly. \ No newline at end of file diff --git a/src/content/changelog/workers/2025-12-02-vite-programmatic-config.mdx b/src/content/changelog/workers/2025-12-02-vite-programmatic-config.mdx index d3d5f8577a32936..81e332233d018c2 100644 --- a/src/content/changelog/workers/2025-12-02-vite-programmatic-config.mdx +++ b/src/content/changelog/workers/2025-12-02-vite-programmatic-config.mdx @@ -10,7 +10,7 @@ The [Cloudflare Vite plugin](/workers/vite-plugin/) now supports programmatic co ## The `config` option -The Vite plugin's new `config` option accepts either a partial configuration object or a function that receives the current configuration and returns overrides. This option is applied after any config file is loaded, allowing the plugin to override specific values or define Workers entirely in code. +The Vite plugin's new `config` option accepts either a partial configuration object or a function that receives the current configuration and returns overrides. This option is applied after any config file is loaded, allowing the plugin to override specific values or define Worker configuration entirely in code. ## Example usage diff --git a/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx b/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx index 863b395333abdcf..5d13221a6424f70 100644 --- a/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx +++ b/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx @@ -10,6 +10,10 @@ import { WranglerConfig } from "~/components"; 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. From 2724e6db8c4b45eb38cc66b8bae651037ca62bd9 Mon Sep 17 00:00:00 2001 From: Matt Kane Date: Tue, 2 Dec 2025 14:16:48 +0000 Subject: [PATCH 7/7] Re-order --- .../vite-plugin/reference/programmatic-configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx b/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx index 5d13221a6424f70..8ec420f1da78ed5 100644 --- a/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx +++ b/src/content/docs/workers/vite-plugin/reference/programmatic-configuration.mdx @@ -2,7 +2,7 @@ pcx_content_type: reference title: Programmatic configuration sidebar: - order: 4 + order: 10 description: Configure Workers programmatically using the Vite plugin ---