From 50f9197557556a6e12b0e5a84db3dd2040f3a48e Mon Sep 17 00:00:00 2001 From: Edmund Hung Date: Fri, 23 Oct 2026 14:45:11 +0100 Subject: [PATCH 1/3] [Workers] Document cloudflare.config.ts support in the Vitest integration --- .../vitest-integration/configuration.mdx | 32 +++++++++++++++++-- .../partials/workers/cloudflare-config.mdx | 1 + 2 files changed, 31 insertions(+), 2 deletions(-) diff --git a/src/content/docs/workers/testing/vitest-integration/configuration.mdx b/src/content/docs/workers/testing/vitest-integration/configuration.mdx index 4d170655bdd..2519d7c1308 100644 --- a/src/content/docs/workers/testing/vitest-integration/configuration.mdx +++ b/src/content/docs/workers/testing/vitest-integration/configuration.mdx @@ -30,6 +30,21 @@ export default defineConfig({ }); ``` +If your project uses a [`cloudflare.config.ts`](/cf/projects/cloudflare-config/) file, set the `config` option instead of `wrangler`: + +```ts +import { cloudflareTest } from "@cloudflare/vitest-plugin"; +import { defineConfig } from "vitest/config"; + +export default defineConfig({ + plugins: [ + cloudflareTest({ + config: true, + }), + ], +}); +``` + :::caution Custom Vitest `environment`s or `runner`s are not supported when using the Workers Vitest integration. @@ -118,8 +133,21 @@ export default defineConfig({ Options passed directly to `cloudflareTest()`. +- `config`: `boolean | string` optional + - Load `main`, [compatibility settings](/workers/configuration/compatibility-dates/), [bindings](/workers/runtime-apis/bindings/), triggers, and exports from a [`cloudflare.config.ts`](/cf/projects/cloudflare-config/) file. Pass `true` to load `cloudflare.config.ts` from the project root, or pass a path to the file relative to the project root. These options are merged with the `miniflare` option, with `miniflare` values taking precedence. You cannot use `config` together with `wrangler`. + + - Function-form configuration receives the Vitest mode as `ctx.mode`. The mode defaults to `test`. To use a different mode, run `vitest --mode `. Refer to [Select a mode](/cf/projects/cloudflare-config/#select-a-mode) for more information. + + - Secret bindings, declared with `bindings.secret()`, are read from files in the Vite [`envDir`](https://vite.dev/config/shared-options#envdir), which is the project root by default. If `.dev.vars.` or `.dev.vars` exists, the integration reads secrets from that file only. Otherwise, it reads `.env`, `.env.local`, `.env.`, and `.env..local`, and environment variables take precedence over these files. These files do not override other bindings. + + - To set a local connection string for a [Hyperdrive](/hyperdrive/) binding, set `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_` in a `.env` file or in the environment. + + - [Remote bindings](/workers/local-development/#remote-bindings) authenticate with `cf` credentials. Sign in with [`cf auth login`](/cf/get-started/#sign-in), or set `CLOUDFLARE_API_TOKEN` in the environment. Apart from Hyperdrive connection strings, the integration reads `CLOUDFLARE_*` variables from the environment only, not from `.env` files. + + - To serve static assets, set the assets directory with `miniflare.assets`. The assets binding and settings from `cloudflare.config.ts` then apply. + - `main`: string optional - - Entry point to Worker run in the same isolate/context as tests. This option is required to use Durable Objects without an explicit `scriptName` if classes are defined in the same Worker. This file goes through Vite transforms and can be TypeScript. Note that `import module from ""` inside tests gives exactly the same `module` instance as is used internally for `exports` and Durable Object bindings. If `wrangler.configPath` is defined and this option is not, it will be read from the `main` field in that configuration file. + - Entry point to Worker run in the same isolate/context as tests. This option is required to use Durable Objects without an explicit `scriptName` if classes are defined in the same Worker. This file goes through Vite transforms and can be TypeScript. Note that `import module from ""` inside tests gives exactly the same `module` instance as is used internally for `exports` and Durable Object bindings. If `wrangler.configPath` is defined and this option is not, it will be read from the `main` field in that configuration file. If `config` is set and this option is not, the integration uses the `entrypoint` from `cloudflare.config.ts`. - `miniflare`: `SourcelessWorkerOptions & { workers?: WorkerOptions\[]; }` optional - Use this to provide configuration information that is typically stored within the [Wrangler configuration file](/workers/wrangler/configuration/), such as [bindings](/workers/runtime-apis/bindings/), [compatibility dates](/workers/configuration/compatibility-dates/), and [compatibility flags](/workers/configuration/compatibility-flags/). The `WorkerOptions` interface is defined [here](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare#interface-workeroptions). Use the `main` option above to configure the entry point, instead of the Miniflare `script`, `scriptPath`, or `modules` options. @@ -134,7 +162,7 @@ Options passed directly to `cloudflareTest()`. - Are not affected by global mocks defined in your tests. - `wrangler`: `{ configPath?: string; environment?: string; }` optional - - Path to [Wrangler configuration file](/workers/wrangler/configuration/) to load `main`, [compatibility settings](/workers/configuration/compatibility-dates/) and [bindings](/workers/runtime-apis/bindings/) from. These options will be merged with the `miniflare` option above, with `miniflare` values taking precedence. For example, if your Wrangler configuration defined a [service binding](/workers/runtime-apis/bindings/service-bindings/) named `SERVICE` to a Worker named `service`, but you included `serviceBindings: { SERVICE(request) { return new Response("body"); } }` in the `miniflare` option, all requests to `SERVICE` in tests would return `body`. Note `configPath` accepts both `.toml` and `.json` files. + - Path to [Wrangler configuration file](/workers/wrangler/configuration/) to load `main`, [compatibility settings](/workers/configuration/compatibility-dates/) and [bindings](/workers/runtime-apis/bindings/) from. These options will be merged with the `miniflare` option above, with `miniflare` values taking precedence. For example, if your Wrangler configuration defined a [service binding](/workers/runtime-apis/bindings/service-bindings/) named `SERVICE` to a Worker named `service`, but you included `serviceBindings: { SERVICE(request) { return new Response("body"); } }` in the `miniflare` option, all requests to `SERVICE` in tests would return `body`. Note `configPath` accepts both `.toml` and `.json` files. You cannot use `wrangler` together with `config`. - The environment option can be used to specify the [Wrangler environment](/workers/wrangler/environments/) to pick up bindings and variables from. diff --git a/src/content/partials/workers/cloudflare-config.mdx b/src/content/partials/workers/cloudflare-config.mdx index ce4f4809392..2feeb47cb1b 100644 --- a/src/content/partials/workers/cloudflare-config.mdx +++ b/src/content/partials/workers/cloudflare-config.mdx @@ -705,6 +705,7 @@ configuration: | Command | Default mode | | ---------------------------------------------------------------- | ------------- | | `cf dev` with the Cloudflare Vite plugin | `development` | +| `vitest` with the Workers Vitest integration | `test` | | `cf build`, `cf deploy`, and other commands that build with Vite | `production` | | Commands that build with Wrangler | `undefined` | | API commands, such as `cf d1 list` | `undefined` | From dd7a2112989236aad78ec565a16d3d83f2c6eaa7 Mon Sep 17 00:00:00 2001 From: Edmund Hung Date: Fri, 23 Oct 2026 16:10:15 +0100 Subject: [PATCH 2/3] [Workers] Document native Miniflare options with the Vitest config option --- .../testing/vitest-integration/configuration.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/content/docs/workers/testing/vitest-integration/configuration.mdx b/src/content/docs/workers/testing/vitest-integration/configuration.mdx index 2519d7c1308..e269eb19312 100644 --- a/src/content/docs/workers/testing/vitest-integration/configuration.mdx +++ b/src/content/docs/workers/testing/vitest-integration/configuration.mdx @@ -134,7 +134,7 @@ export default defineConfig({ Options passed directly to `cloudflareTest()`. - `config`: `boolean | string` optional - - Load `main`, [compatibility settings](/workers/configuration/compatibility-dates/), [bindings](/workers/runtime-apis/bindings/), triggers, and exports from a [`cloudflare.config.ts`](/cf/projects/cloudflare-config/) file. Pass `true` to load `cloudflare.config.ts` from the project root, or pass a path to the file relative to the project root. These options are merged with the `miniflare` option, with `miniflare` values taking precedence. You cannot use `config` together with `wrangler`. + - Load `main`, [compatibility settings](/workers/configuration/compatibility-dates/), [bindings](/workers/runtime-apis/bindings/), triggers, and exports from a [`cloudflare.config.ts`](/cf/projects/cloudflare-config/) file. Pass `true` to load `cloudflare.config.ts` from the project root, or pass a path to the file relative to the project root. You cannot use `config` together with `wrangler`. - Function-form configuration receives the Vitest mode as `ctx.mode`. The mode defaults to `test`. To use a different mode, run `vitest --mode `. Refer to [Select a mode](/cf/projects/cloudflare-config/#select-a-mode) for more information. @@ -144,12 +144,18 @@ Options passed directly to `cloudflareTest()`. - [Remote bindings](/workers/local-development/#remote-bindings) authenticate with `cf` credentials. Sign in with [`cf auth login`](/cf/get-started/#sign-in), or set `CLOUDFLARE_API_TOKEN` in the environment. Apart from Hyperdrive connection strings, the integration reads `CLOUDFLARE_*` variables from the environment only, not from `.env` files. - - To serve static assets, set the assets directory with `miniflare.assets`. The assets binding and settings from `cloudflare.config.ts` then apply. + - With `config`, the `miniflare` option takes native Miniflare Worker options, which are merged over `cloudflare.config.ts`: + - `miniflare.config` sets Worker settings, such as `env`, `triggers`, and `assets`. Bindings in `env` replace bindings with the same name in `cloudflare.config.ts`, and queue triggers replace the triggers for the same queue. Other settings replace those in `cloudflare.config.ts`. + - `miniflare.dev` sets development settings, such as `outboundService`. + - `miniflare.workers` defines auxiliary Workers, each in the native Miniflare Worker shape. + + - To serve static assets, set `miniflare.config.assets.directory`. The assets binding and settings from `cloudflare.config.ts` then apply. - `main`: string optional - Entry point to Worker run in the same isolate/context as tests. This option is required to use Durable Objects without an explicit `scriptName` if classes are defined in the same Worker. This file goes through Vite transforms and can be TypeScript. Note that `import module from ""` inside tests gives exactly the same `module` instance as is used internally for `exports` and Durable Object bindings. If `wrangler.configPath` is defined and this option is not, it will be read from the `main` field in that configuration file. If `config` is set and this option is not, the integration uses the `entrypoint` from `cloudflare.config.ts`. - `miniflare`: `SourcelessWorkerOptions & { workers?: WorkerOptions\[]; }` optional + - If `config` is set, this option takes native Miniflare Worker options instead. Refer to the `config` option above. - Use this to provide configuration information that is typically stored within the [Wrangler configuration file](/workers/wrangler/configuration/), such as [bindings](/workers/runtime-apis/bindings/), [compatibility dates](/workers/configuration/compatibility-dates/), and [compatibility flags](/workers/configuration/compatibility-flags/). The `WorkerOptions` interface is defined [here](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare#interface-workeroptions). Use the `main` option above to configure the entry point, instead of the Miniflare `script`, `scriptPath`, or `modules` options. - If no `compatibility_date` is provided, then the test will use the latest locally available date. From 7111ad59e9f62dc4825ce575ce532e5aacf68435 Mon Sep 17 00:00:00 2001 From: Edmund Hung Date: Fri, 23 Oct 2026 17:28:33 +0100 Subject: [PATCH 3/3] [Workers] Note that miniflare can't be combined with the Vitest config option --- .../testing/vitest-integration/configuration.mdx | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/src/content/docs/workers/testing/vitest-integration/configuration.mdx b/src/content/docs/workers/testing/vitest-integration/configuration.mdx index e269eb19312..0aa2db4e47d 100644 --- a/src/content/docs/workers/testing/vitest-integration/configuration.mdx +++ b/src/content/docs/workers/testing/vitest-integration/configuration.mdx @@ -134,7 +134,7 @@ export default defineConfig({ Options passed directly to `cloudflareTest()`. - `config`: `boolean | string` optional - - Load `main`, [compatibility settings](/workers/configuration/compatibility-dates/), [bindings](/workers/runtime-apis/bindings/), triggers, and exports from a [`cloudflare.config.ts`](/cf/projects/cloudflare-config/) file. Pass `true` to load `cloudflare.config.ts` from the project root, or pass a path to the file relative to the project root. You cannot use `config` together with `wrangler`. + - Load `main`, [compatibility settings](/workers/configuration/compatibility-dates/), [bindings](/workers/runtime-apis/bindings/), triggers, and exports from a [`cloudflare.config.ts`](/cf/projects/cloudflare-config/) file. Pass `true` to load `cloudflare.config.ts` from the project root, or pass a path to the file relative to the project root. You cannot use `config` together with `wrangler` or `miniflare`. - Function-form configuration receives the Vitest mode as `ctx.mode`. The mode defaults to `test`. To use a different mode, run `vitest --mode `. Refer to [Select a mode](/cf/projects/cloudflare-config/#select-a-mode) for more information. @@ -144,18 +144,11 @@ Options passed directly to `cloudflareTest()`. - [Remote bindings](/workers/local-development/#remote-bindings) authenticate with `cf` credentials. Sign in with [`cf auth login`](/cf/get-started/#sign-in), or set `CLOUDFLARE_API_TOKEN` in the environment. Apart from Hyperdrive connection strings, the integration reads `CLOUDFLARE_*` variables from the environment only, not from `.env` files. - - With `config`, the `miniflare` option takes native Miniflare Worker options, which are merged over `cloudflare.config.ts`: - - `miniflare.config` sets Worker settings, such as `env`, `triggers`, and `assets`. Bindings in `env` replace bindings with the same name in `cloudflare.config.ts`, and queue triggers replace the triggers for the same queue. Other settings replace those in `cloudflare.config.ts`. - - `miniflare.dev` sets development settings, such as `outboundService`. - - `miniflare.workers` defines auxiliary Workers, each in the native Miniflare Worker shape. - - - To serve static assets, set `miniflare.config.assets.directory`. The assets binding and settings from `cloudflare.config.ts` then apply. - - `main`: string optional - Entry point to Worker run in the same isolate/context as tests. This option is required to use Durable Objects without an explicit `scriptName` if classes are defined in the same Worker. This file goes through Vite transforms and can be TypeScript. Note that `import module from ""` inside tests gives exactly the same `module` instance as is used internally for `exports` and Durable Object bindings. If `wrangler.configPath` is defined and this option is not, it will be read from the `main` field in that configuration file. If `config` is set and this option is not, the integration uses the `entrypoint` from `cloudflare.config.ts`. - `miniflare`: `SourcelessWorkerOptions & { workers?: WorkerOptions\[]; }` optional - - If `config` is set, this option takes native Miniflare Worker options instead. Refer to the `config` option above. + - You cannot use `miniflare` together with `config`. - Use this to provide configuration information that is typically stored within the [Wrangler configuration file](/workers/wrangler/configuration/), such as [bindings](/workers/runtime-apis/bindings/), [compatibility dates](/workers/configuration/compatibility-dates/), and [compatibility flags](/workers/configuration/compatibility-flags/). The `WorkerOptions` interface is defined [here](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare#interface-workeroptions). Use the `main` option above to configure the entry point, instead of the Miniflare `script`, `scriptPath`, or `modules` options. - If no `compatibility_date` is provided, then the test will use the latest locally available date.