Vite plugin docs

src/content/docs/workers/vite-plugin/api.mdx

@@ -0,0 +1,87 @@
+---
+pcx_content_type: reference
+title: API
+head: []
+sidebar:
+  order: 3
+description: Vite plugin API
+---
+
+### `cloudflare()`
+
+The `cloudflare` plugin should be included in the Vite `plugins` array:
+
+```ts {4, 7}
+// vite.config.ts
+
+import { defineConfig } from "vite";
+import { cloudflare } from "@cloudflare/vite-plugin";
+
+export default defineConfig({
+	plugins: [cloudflare()],
+});
+```
+
+It accepts an optional `PluginConfig` parameter.
+
+### `interface PluginConfig`
+
+- `configPath?: string`
+
+  An optional path to your Worker config file.
+  By default, a `wrangler.jsonc`, `wrangler.json`, or `wrangler.toml` file in the root of your application will be used as the Worker config.
+
+  For more information about the Worker configuration, see [Configuration](/workers/wrangler/configuration/).
+
+- `viteEnvironment?: { name?: string }`
+
+  Optional Vite environment options.
+  By default, the environment name is the Worker name with `-` characters replaced with `_`.
+  Setting the name here will override this.
+  A typical use case is setting `viteEnvironment: { name: "ssr" }` to apply the Worker to the SSR environment.
+
+  See [Vite Environments](/workers/vite-plugin/vite-environments/) for more information.
+
+- `persistState?: boolean | { path: string }`
+
+  An optional override for state persistence.
+  By default, state is persisted to `.wrangler/state`.
+  A custom `path` can be provided or, alternatively, persistence can be disabled by setting the value to `false`.
+
+- `inspectorPort?: number | false`
+
+  An optional override for debugging your Workers.
+  By default, the debugging inspector is enabled and listens on port `9229`.
+  A custom port can be provided or, alternatively, setting this to `false` will disable the debugging inspector.
+
+  See [Debugging](/workers/vite-plugin/debugging/) for more information.
+
+- `auxiliaryWorkers?: Array<AuxiliaryWorkerConfig>`
+
+  An optional array of auxiliary Workers.
+  Auxiliary Workers are additional Workers that are used as part of your application.
+  You can use [service bindings](/workers/runtime-apis/bindings/service-bindings/) to call auxiliary Workers from your main (entry) Worker.
+  All requests are routed through your entry Worker.
+  During the build, each Worker is output to a separate subdirectory of `dist`.
+
+:::note
+When running `wrangler deploy`, only your main (entry) Worker will be deployed.
+If using multiple Workers, each auxiliary Worker must be deployed individually.
+You can inspect the `dist` directory and then run `wrangler deploy -c dist/<auxiliary-worker>/wrangler.json` for each.
+:::
+
+### `interface AuxiliaryWorkerConfig`
+
+- `configPath: string`
+
+  A required path to your Worker config file.
+
+  For more information about the Worker configuration, see [Configuration](/workers/wrangler/configuration/).
+
+- `viteEnvironment?: { name?: string }`
+
+  Optional Vite environment options.
+  By default, the environment name is the Worker name with `-` characters replaced with `_`.
+  Setting the name here will override this.
+
+  See [Vite Environments](/workers/vite-plugin/vite-environments/) for more information.

src/content/docs/workers/vite-plugin/cloudflare-environments.mdx

@@ -0,0 +1,110 @@
+---
+pcx_content_type: reference
+title: Cloudflare Environments
+head: []
+sidebar:
+  order: 9
+description: Using Cloudflare environments with the Vite plugin
+---
+
+import { PackageManagers, WranglerConfig } from "~/components";
+
+A Worker config file may contain configuration for multiple [Cloudflare environments](/workers/wrangler/environments/).
+With the Cloudflare Vite plugin, you select a Cloudflare environment at dev or build time by providing the `CLOUDFLARE_ENV` environment variable.
+Consider the following example Worker config file:
+
+<WranglerConfig>
+
+```toml
+name = "my-worker"
+compatibility_date = "2025-04-03"
+main = "./src/index.ts"
+
+vars = { MY_VAR = "Top-level var" }
+
+[env.staging]
+vars = { MY_VAR = "Staging var" }
+
+[env.production]
+vars = { MY_VAR = "Production var" }
+```
+
+</WranglerConfig>
+
+If you run `CLOUDFLARE_ENV=production vite build` then the output `wrangler.json` file generated by the build will be a flattened configuration for the 'production' Cloudflare environment, as shown in the following example:
+
+```json
+{
+	"name": "my-worker",
+	"compatibility_date": "2025-04-03",
+	"main": "index.js",
+	"vars": { "MY_VAR": "Production var" }
+}
+```
+
+Notice that the value of `MY_VAR` is `Production var`.
+This flattened configuration combines [top-level only](/workers/wrangler/configuration/#top-level-only-keys), [inheritable](/workers/wrangler/configuration/#inheritable-keys), and [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) keys.
+
+:::note
+The default Vite environment name for a Worker is always the top-level Worker name.
+This enables you to reference the Worker consistently in your Vite config when using multiple Cloudflare environments.
+See [Vite Environments](/workers/vite-plugin/vite-environments/) for more information.
+:::
+
+Cloudflare environments can also be used in development.
+For example, you could run `CLOUDFLARE_ENV=development vite dev`.
+It is common to use the default top-level environment as the development environment and then add additional environments as necessary.
+
+:::note
+Running `vite dev` or `vite build` without providing `CLOUDFLARE_ENV` will use the default top-level Cloudflare environment.
+As Cloudflare environments are applied at dev and build time, specifying `CLOUDFLARE_ENV` when running `vite preview` or `wrangler deploy` will have no effect.
+:::
+
+### Combining Cloudflare environments and Vite modes
+
+You may wish to combine the concepts of [Cloudflare environments](/workers/wrangler/environments/) and [Vite modes](https://vite.dev/guide/env-and-mode.html#modes).
+With this approach, the Vite mode can be used to select the Cloudflare environment and a single method can be used to determine environment specific configuration and code.
+Consider again the previous example:
+
+<WranglerConfig>
+
+```toml
+# wrangler.toml
+
+name = "my-worker"
+compatibility_date = "2025-04-03"
+main = "./src/index.ts"
+
+vars = { MY_VAR = "Top-level var" }
+
+[env.staging]
+vars = { MY_VAR = "Staging var" }
+
+[env.production]
+vars = { MY_VAR = "Production var" }
+```
+
+</WranglerConfig>
+
+Next, provide `.env.staging` and `.env.production` files:
+
+```sh
+# .env.staging
+
+CLOUDFLARE_ENV=staging
+```
+
+```sh
+# .env.production
+
+CLOUDFLARE_ENV=production
+```
+
+By default, `vite build` uses the 'production' Vite mode.
+Vite will therefore load the `.env.production` file to get the environment variables that are used in the build.
+Since the `.env.production` file contains `CLOUDFLARE_ENV=production`, the Cloudflare Vite plugin will select the 'production' Cloudflare environment.
+The value of `MY_VAR` will therefore be `'Production var'`.
+If you run `vite build --mode staging` then the 'staging' Vite mode will be used and the 'staging' Cloudflare environment will be selected.
+The value of `MY_VAR` will therefore be `'Staging var'`.
+
+For more information about using `.env` files with Vite, see the [relevant documentation](https://vite.dev/guide/env-and-mode#env-files).

src/content/docs/workers/vite-plugin/debugging.mdx

@@ -0,0 +1,60 @@
+---
+pcx_content_type: reference
+title: Debugging
+head: []
+sidebar:
+  order: 5
+description: Debugging with the Vite plugin
+---
+
+The Cloudflare Vite plugin has debugging enabled by default and listens on port `9229`.
+You may choose a custom port or disable debugging by setting the `inspectorPort` option in the [plugin config](/workers/vite-plugin/api#interface-pluginconfig).
+There are two recommended methods for debugging your Workers during local development:
+
+### DevTools
+
+When running `vite dev` or `vite preview`, a `/__debug` route is added that provides access to [Cloudflare's implementation](https://github.com/cloudflare/workers-sdk/tree/main/packages/chrome-devtools-patches) of [Chrome's DevTools](https://developer.chrome.com/docs/devtools/overview).
+Navigating to this route will open a DevTools tab for each of the Workers in your application.
+
+Once the tab(s) are open, you can make a request to your application and start debugging your Worker code.
+
+:::note
+When debugging multiple Workers, you may need to allow your browser to open pop-ups.
+:::
+
+### VS Code
+
+To set up [VS Code](https://code.visualstudio.com/) to support breakpoint debugging in your application, you should create a `.vscode/launch.json` file that contains the following configuration:
+
+```json
+{
+	"configurations": [
+		{
+			"name": "<NAME_OF_WORKER>",
+			"type": "node",
+			"request": "attach",
+			"websocketAddress": "ws://localhost:9229/<NAME_OF_WORKER>",
+			"resolveSourceMapLocations": null,
+			"attachExistingChildren": false,
+			"autoAttachChildProcesses": false,
+			"sourceMaps": true
+		}
+	],
+	"compounds": [
+		{
+			"name": "Debug Workers",
+			"configurations": ["<NAME_OF_WORKER>"],
+			"stopAll": true
+		}
+	]
+}
+```
+
+Here, `<NAME_OF_WORKER>` indicates the name of the Worker as specified in your Worker config file.
+If you have used the `inspectorPort` option to set a custom port then this should be the value provided in the `websocketaddress` field.
+
+:::note
+If you have more than one Worker in your application, you should add a configuration in the `configurations` field for each and include the configuration name in the `compounds` `configurations` array.
+:::
+
+With this set up, you can run `vite dev` or `vite preview` and then select **Debug Workers** at the top of the **Run & Debug** panel to start debugging.

src/content/docs/workers/vite-plugin/get-started.mdx

@@ -0,0 +1,93 @@
+---
+pcx_content_type: get-started
+title: Get started
+head: []
+sidebar:
+  order: 1
+description: Get started with the Vite plugin
+---
+
+import { PackageManagers, WranglerConfig } from "~/components";
+
+:::note
+This guide demonstrates creating a standalone Worker from scratch.
+{/* Add link to React Router framework guide */}If you would instead like to create a new application from a ready-to-go template, refer to the [React](/workers/frameworks/framework-guides/react/) or [Vue](/workers/frameworks/framework-guides/vue/) framework guides.
+:::
+
+### Start with a basic `package.json`
+
+```json
+{
+	"name": "cloudflare-vite-quick-start",
+	"private": true,
+	"version": "0.0.0",
+	"type": "module",
+	"scripts": {
+		"dev": "vite",
+		"build": "vite build",
+		"preview": "vite preview",
+		"deploy": "wrangler deploy"
+	}
+}
+```
+
+:::note
+Ensure that you include `"type": "module"` in order to use ES modules by default.
+:::
+
+### Install the dependencies
+
+<PackageManagers type="add" pkg="vite @cloudflare/vite-plugin wrangler" dev />
+
+### Create your Vite config file and include the Cloudflare plugin
+
+```ts
+// vite.config.ts
+
+import { defineConfig } from "vite";
+import { cloudflare } from "@cloudflare/vite-plugin";
+
+export default defineConfig({
+	plugins: [cloudflare()],
+});
+```
+
+The Cloudflare Vite plugin doesn't require any configuration by default and will look for a `wrangler.jsonc`, `wrangler.json` or `wrangler.toml` in the root of your application.
+
+Refer to the [API reference](/workers/vite-plugin/api/) for configuration options.
+
+### Create your Worker config file
+
+<WranglerConfig>
+
+```toml
+name = "cloudflare-vite-quick-start"
+compatibility_date = "2025-04-03"
+main = "./src/index.ts"
+```
+
+</WranglerConfig>
+
+The `name` field specifies the name of your Worker.
+By default, this is also used as the name of the Worker's Vite Environment (see [Vite Environments](/workers/vite-plugin/vite-environments/) for more information).
+The `main` field specifies the entry file for your Worker code.
+
+For more information about the Worker configuration, see [Configuration](/workers/wrangler/configuration/).
+
+### Create your Worker entry file
+
+```ts
+// src/index.ts
+
+export default {
+	fetch() {
+		return new Response(`Running in ${navigator.userAgent}!`);
+	},
+};
+```
+
+A request to this Worker will return 'Running in Cloudflare-Workers!', demonstrating that the code is running inside the Workers runtime.
+
+### Dev, build, preview and deploy
+
+You can now start the Vite development server (`npm run dev`), build the application (`npm run build`), preview the built application (`npm run preview`), and deploy to Cloudflare (`npm run deploy`).

src/content/docs/workers/vite-plugin/index.mdx

@@ -0,0 +1,35 @@
+---
+pcx_content_type: overview
+title: Vite plugin
+sidebar:
+  order: 16
+head: []
+description: A full-featured integration between Vite and the Workers runtime
+---
+
+The Cloudflare Vite plugin enables a full-featured integration between Vite and the Workers runtime.
+Your Worker code runs inside [workerd](https://github.com/cloudflare/workerd), matching the production behavior as closely as possible and providing confidence as you develop and deploy your applications.
+
+### Features
+
+- Uses the Vite [Environment API](https://vite.dev/guide/api-environment) to integrate Vite with the Workers runtime
+- Provides direct access to Workers runtime APIs and bindings
+- Builds your front-end assets for deployment to Cloudflare, enabling you to build static sites, SPAs, and full-stack applications
+- Official support for [React Router v7](https://reactrouter.com/) with server-side rendering
+- Leverages Vite's hot module replacement for consistently fast updates
+- Supports `vite preview` for previewing your build output in the Workers runtime prior to deployment
+
+### Use cases
+
+- React Router v7 (support for more full-stack frameworks is coming soon)
+- Static sites, such as single-page applications, with or without an integrated backend API
+- Standalone Workers
+- Multi-Worker applications
+
+### Get started
+
+{/* Add link to React Router framework guide */}To create a new application from a ready-to-go template, refer to the [React](/workers/frameworks/framework-guides/react/) or [Vue](/workers/frameworks/framework-guides/vue/) framework guides.
+
+To create a standalone Worker from scratch, refer to [Get started](/workers/vite-plugin/get-started/).
+
+For a more in-depth look at adapting an existing Vite project and an introduction to key concepts, refer to the [Tutorial](/workers/vite-plugin/tutorial/).