Skip to content

Commit 03c433a

Browse files
jamesopstadjamesopstad
authored
Vite plugin docs (#20481)
1 parent 939c5fd commit 03c433a

File tree

11 files changed

+849
-0
lines changed

11 files changed

+849
-0
lines changed

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

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
pcx_content_type: get-started
3+
title: Get started
4+
sidebar:
5+
order: 1
6+
description: Get started with the Vite plugin
7+
---
8+
9+
import { PackageManagers, WranglerConfig } from "~/components";
10+
11+
:::note
12+
This guide demonstrates creating a standalone Worker from scratch.
13+
{/* 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.
14+
:::
15+
16+
## Start with a basic `package.json`
17+
18+
```json title="package.json"
19+
{
20+
"name": "cloudflare-vite-get-started",
21+
"private": true,
22+
"version": "0.0.0",
23+
"type": "module",
24+
"scripts": {
25+
"dev": "vite dev",
26+
"build": "vite build",
27+
"preview": "npm run build && vite preview",
28+
"deploy": "npm run build && wrangler deploy"
29+
}
30+
}
31+
```
32+
33+
:::note
34+
Ensure that you include `"type": "module"` in order to use ES modules by default.
35+
:::
36+
37+
## Install the dependencies
38+
39+
<PackageManagers type="add" pkg="vite @cloudflare/vite-plugin wrangler" dev />
40+
41+
## Create your Vite config file and include the Cloudflare plugin
42+
43+
```ts title="vite.config.ts"
44+
import { defineConfig } from "vite";
45+
import { cloudflare } from "@cloudflare/vite-plugin";
46+
47+
export default defineConfig({
48+
plugins: [cloudflare()],
49+
});
50+
```
51+
52+
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.
53+
54+
Refer to the [API reference](/workers/vite-plugin/reference/api/) for configuration options.
55+
56+
## Create your Worker config file
57+
58+
<WranglerConfig>
59+
60+
```toml
61+
name = "cloudflare-vite-get-started"
62+
compatibility_date = "2025-04-03"
63+
main = "./src/index.ts"
64+
```
65+
66+
</WranglerConfig>
67+
68+
The `name` field specifies the name of your Worker.
69+
By default, this is also used as the name of the Worker's Vite Environment (see [Vite Environments](/workers/vite-plugin/reference/vite-environments/) for more information).
70+
The `main` field specifies the entry file for your Worker code.
71+
72+
For more information about the Worker configuration, see [Configuration](/workers/wrangler/configuration/).
73+
74+
## Create your Worker entry file
75+
76+
```ts title="src/index.ts"
77+
export default {
78+
fetch() {
79+
return new Response(`Running in ${navigator.userAgent}!`);
80+
},
81+
};
82+
```
83+
84+
A request to this Worker will return 'Running in Cloudflare-Workers!', demonstrating that the code is running inside the Workers runtime.
85+
86+
## Dev, build, preview and deploy
87+
88+
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‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
pcx_content_type: overview
3+
title: Vite plugin
4+
sidebar:
5+
order: 16
6+
description: A full-featured integration between Vite and the Workers runtime
7+
---
8+
9+
The Cloudflare Vite plugin enables a full-featured integration between [Vite](https://vite.dev/) and the [Workers runtime](/workers/runtime-apis/).
10+
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.
11+
12+
### Features
13+
14+
- Uses the Vite [Environment API](https://vite.dev/guide/api-environment) to integrate Vite with the Workers runtime
15+
- Provides direct access to [Workers runtime APIs](/workers/runtime-apis/) and [bindings](/workers/runtime-apis/bindings/)
16+
- Builds your front-end assets for deployment to Cloudflare, enabling you to build static sites, SPAs, and full-stack applications
17+
- Official support for [React Router v7](https://reactrouter.com/) with server-side rendering
18+
- Leverages Vite's hot module replacement for consistently fast updates
19+
- Supports `vite preview` for previewing your build output in the Workers runtime prior to deployment
20+
21+
### Use cases
22+
23+
- React Router v7 (support for more full-stack frameworks is coming soon)
24+
- Static sites, such as single-page applications, with or without an integrated backend API
25+
- Standalone Workers
26+
- Multi-Worker applications
27+
28+
### Get started
29+
30+
{/* 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.
31+
32+
To create a standalone Worker from scratch, refer to [Get started](/workers/vite-plugin/get-started/).
33+
34+
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/).

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

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
pcx_content_type: reference
3+
title: API
4+
sidebar:
5+
order: 3
6+
description: Vite plugin API
7+
---
8+
9+
import { Type, MetaInfo } from "~/components";
10+
11+
## `cloudflare()`
12+
13+
The `cloudflare` plugin should be included in the Vite `plugins` array:
14+
15+
```ts {2, 5} title="vite.config.ts"
16+
import { defineConfig } from "vite";
17+
import { cloudflare } from "@cloudflare/vite-plugin";
18+
19+
export default defineConfig({
20+
plugins: [cloudflare()],
21+
});
22+
```
23+
24+
It accepts an optional `PluginConfig` parameter.
25+
26+
## `interface PluginConfig`
27+
28+
- `configPath` <Type text='string' /> <MetaInfo text='optional' />
29+
30+
An optional path to your Worker config file.
31+
By default, a `wrangler.jsonc`, `wrangler.json`, or `wrangler.toml` file in the root of your application will be used as the Worker config.
32+
33+
For more information about the Worker configuration, see [Configuration](/workers/wrangler/configuration/).
34+
35+
- `viteEnvironment` <Type text='{ name?: string }' /> <MetaInfo text='optional' />
36+
37+
Optional Vite environment options.
38+
By default, the environment name is the Worker name with `-` characters replaced with `_`.
39+
Setting the name here will override this.
40+
A typical use case is setting `viteEnvironment: { name: "ssr" }` to apply the Worker to the SSR environment.
41+
42+
See [Vite Environments](/workers/vite-plugin/reference/vite-environments/) for more information.
43+
44+
- `persistState` <Type text='boolean | { path: string }' /> <MetaInfo text='optional' />
45+
46+
An optional override for state persistence.
47+
By default, state is persisted to `.wrangler/state`.
48+
A custom `path` can be provided or, alternatively, persistence can be disabled by setting the value to `false`.
49+
50+
- `inspectorPort` <Type text='number | false' /> <MetaInfo text='optional' />
51+
52+
An optional override for debugging your Workers.
53+
By default, the debugging inspector is enabled and listens on port `9229`.
54+
A custom port can be provided or, alternatively, setting this to `false` will disable the debugging inspector.
55+
56+
See [Debugging](/workers/vite-plugin/reference/debugging/) for more information.
57+
58+
- `auxiliaryWorkers` <Type text='Array<AuxiliaryWorkerConfig>' /> <MetaInfo text='optional' />
59+
60+
An optional array of auxiliary Workers.
61+
Auxiliary Workers are additional Workers that are used as part of your application.
62+
You can use [service bindings](/workers/runtime-apis/bindings/service-bindings/) to call auxiliary Workers from your main (entry) Worker.
63+
All requests are routed through your entry Worker.
64+
During the build, each Worker is output to a separate subdirectory of `dist`.
65+
66+
:::note
67+
When running `wrangler deploy`, only your main (entry) Worker will be deployed.
68+
If using multiple Workers, each auxiliary Worker must be deployed individually.
69+
You can inspect the `dist` directory and then run `wrangler deploy -c dist/<auxiliary-worker>/wrangler.json` for each.
70+
:::
71+
72+
## `interface AuxiliaryWorkerConfig`
73+
74+
- `configPath` <Type text='string' />
75+
76+
A required path to your Worker config file.
77+
78+
For more information about the Worker configuration, see [Configuration](/workers/wrangler/configuration/).
79+
80+
- `viteEnvironment` <Type text='{ name?: string }' /> <MetaInfo text='optional' />
81+
82+
Optional Vite environment options.
83+
By default, the environment name is the Worker name with `-` characters replaced with `_`.
84+
Setting the name here will override this.
85+
86+
See [Vite Environments](/workers/vite-plugin/reference/vite-environments/) for more information.

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

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
pcx_content_type: reference
3+
title: Cloudflare Environments
4+
sidebar:
5+
order: 9
6+
description: Using Cloudflare environments with the Vite plugin
7+
---
8+
9+
import { PackageManagers, WranglerConfig } from "~/components";
10+
11+
A Worker config file may contain configuration for multiple [Cloudflare environments](/workers/wrangler/environments/).
12+
With the Cloudflare Vite plugin, you select a Cloudflare environment at dev or build time by providing the `CLOUDFLARE_ENV` environment variable.
13+
Consider the following example Worker config file:
14+
15+
<WranglerConfig>
16+
17+
```toml
18+
name = "my-worker"
19+
compatibility_date = "2025-04-03"
20+
main = "./src/index.ts"
21+
22+
vars = { MY_VAR = "Top-level var" }
23+
24+
[env.staging]
25+
vars = { MY_VAR = "Staging var" }
26+
27+
[env.production]
28+
vars = { MY_VAR = "Production var" }
29+
```
30+
31+
</WranglerConfig>
32+
33+
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:
34+
35+
```json title=wrangler.json
36+
{
37+
"name": "my-worker",
38+
"compatibility_date": "2025-04-03",
39+
"main": "index.js",
40+
"vars": { "MY_VAR": "Production var" }
41+
}
42+
```
43+
44+
Notice that the value of `MY_VAR` is `Production var`.
45+
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.
46+
47+
:::note
48+
The default Vite environment name for a Worker is always the top-level Worker name.
49+
This enables you to reference the Worker consistently in your Vite config when using multiple Cloudflare environments.
50+
See [Vite Environments](/workers/vite-plugin/reference/vite-environments/) for more information.
51+
:::
52+
53+
Cloudflare environments can also be used in development.
54+
For example, you could run `CLOUDFLARE_ENV=development vite dev`.
55+
It is common to use the default top-level environment as the development environment and then add additional environments as necessary.
56+
57+
:::note
58+
Running `vite dev` or `vite build` without providing `CLOUDFLARE_ENV` will use the default top-level Cloudflare environment.
59+
As Cloudflare environments are applied at dev and build time, specifying `CLOUDFLARE_ENV` when running `vite preview` or `wrangler deploy` will have no effect.
60+
:::
61+
62+
## Combining Cloudflare environments and Vite modes
63+
64+
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).
65+
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.
66+
Consider again the previous example:
67+
68+
<WranglerConfig>
69+
70+
```toml
71+
# wrangler.toml
72+
73+
name = "my-worker"
74+
compatibility_date = "2025-04-03"
75+
main = "./src/index.ts"
76+
77+
vars = { MY_VAR = "Top-level var" }
78+
79+
[env.staging]
80+
vars = { MY_VAR = "Staging var" }
81+
82+
[env.production]
83+
vars = { MY_VAR = "Production var" }
84+
```
85+
86+
</WranglerConfig>
87+
88+
Next, provide `.env.staging` and `.env.production` files:
89+
90+
```sh
91+
# .env.staging
92+
93+
CLOUDFLARE_ENV=staging
94+
```
95+
96+
```sh
97+
# .env.production
98+
99+
CLOUDFLARE_ENV=production
100+
```
101+
102+
By default, `vite build` uses the 'production' Vite mode.
103+
Vite will therefore load the `.env.production` file to get the environment variables that are used in the build.
104+
Since the `.env.production` file contains `CLOUDFLARE_ENV=production`, the Cloudflare Vite plugin will select the 'production' Cloudflare environment.
105+
The value of `MY_VAR` will therefore be `'Production var'`.
106+
If you run `vite build --mode staging` then the 'staging' Vite mode will be used and the 'staging' Cloudflare environment will be selected.
107+
The value of `MY_VAR` will therefore be `'Staging var'`.
108+
109+
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/reference/debugging.mdx‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
pcx_content_type: reference
3+
title: Debugging
4+
sidebar:
5+
order: 5
6+
description: Debugging with the Vite plugin
7+
---
8+
9+
The Cloudflare Vite plugin has debugging enabled by default and listens on port `9229`.
10+
You may choose a custom port or disable debugging by setting the `inspectorPort` option in the [plugin config](/workers/vite-plugin/reference/api#interface-pluginconfig).
11+
There are two recommended methods for debugging your Workers during local development:
12+
13+
## DevTools
14+
15+
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).
16+
Navigating to this route will open a DevTools tab for each of the Workers in your application.
17+
18+
Once the tab(s) are open, you can make a request to your application and start debugging your Worker code.
19+
20+
:::note
21+
When debugging multiple Workers, you may need to allow your browser to open pop-ups.
22+
:::
23+
24+
## VS Code
25+
26+
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:
27+
28+
```json title=".vscode/launch.json"
29+
{
30+
"configurations": [
31+
{
32+
"name": "<NAME_OF_WORKER>",
33+
"type": "node",
34+
"request": "attach",
35+
"websocketAddress": "ws://localhost:9229/<NAME_OF_WORKER>",
36+
"resolveSourceMapLocations": null,
37+
"attachExistingChildren": false,
38+
"autoAttachChildProcesses": false,
39+
"sourceMaps": true
40+
}
41+
],
42+
"compounds": [
43+
{
44+
"name": "Debug Workers",
45+
"configurations": ["<NAME_OF_WORKER>"],
46+
"stopAll": true
47+
}
48+
]
49+
}
50+
```
51+
52+
Here, `<NAME_OF_WORKER>` indicates the name of the Worker as specified in your Worker config file.
53+
If you have used the `inspectorPort` option to set a custom port then this should be the value provided in the `websocketaddress` field.
54+
55+
:::note
56+
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.
57+
:::
58+
59+
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/reference/index.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
pcx_content_type: navigation
3+
title: Reference
4+
sidebar:
5+
order: 5
6+
group:
7+
hideIndex: true
8+
---
9+
10+
import { DirectoryListing } from "~/components";
11+
12+
<DirectoryListing />

0 commit comments

Comments
 (0)