Skip to content

Commit 7e7f416

Browse files
jamesopstadjamesopstad
committed
Initial Vite plugin docs
1 parent d534f62 commit 7e7f416

File tree

7 files changed

+553
-0
lines changed

7 files changed

+553
-0
lines changed

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

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

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

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

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

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
pcx_content_type: get-started
3+
title: Get started
4+
head: []
5+
sidebar:
6+
order: 1
7+
description: Get started with the Vite plugin
8+
---
9+
10+
import { PackageManagers, WranglerConfig } from "~/components";
11+
12+
### Start with a basic `package.json`
13+
14+
```json
15+
{
16+
"name": "cloudflare-vite-quick-start",
17+
"private": true,
18+
"version": "0.0.0",
19+
"type": "module",
20+
"scripts": {
21+
"dev": "vite",
22+
"build": "vite build",
23+
"preview": "vite preview"
24+
}
25+
}
26+
```
27+
28+
:::note
29+
Ensure that you include `"type": "module"` in order to use ES modules by default.
30+
:::
31+
32+
### Install the dependencies
33+
34+
<PackageManagers type="add" pkg="vite @cloudflare/vite-plugin wrangler" dev />
35+
36+
### Create your Vite config file and include the Cloudflare plugin
37+
38+
```ts
39+
// vite.config.ts
40+
41+
import { defineConfig } from "vite";
42+
import { cloudflare } from "@cloudflare/vite-plugin";
43+
44+
export default defineConfig({
45+
plugins: [cloudflare()],
46+
});
47+
```
48+
49+
### Create your Worker config file
50+
51+
<WranglerConfig>
52+
53+
```toml
54+
name = "cloudflare-vite-quick-start"
55+
compatibility_date = "2024-12-30"
56+
main = "./src/index.ts"
57+
```
58+
59+
</WranglerConfig>
60+
61+
### Create your Worker entry file
62+
63+
```ts
64+
// src/index.ts
65+
66+
export default {
67+
fetch() {
68+
return new Response(`Running in ${navigator.userAgent}!`);
69+
},
70+
};
71+
```
72+
73+
You can now develop (`npm run dev`), build (`npm run build`), preview (`npm run preview`), and deploy (`npm exec wrangler deploy`) your application.

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

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
pcx_content_type: overview
3+
title: Vite plugin
4+
sidebar:
5+
# order:
6+
group:
7+
badge: Beta
8+
head: []
9+
description: A full-featured integration between Vite and the Workers runtime
10+
---
11+
12+
The Cloudflare Vite plugin enables a full-featured integration between Vite and the Workers runtime.
13+
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.
14+
15+
### Features
16+
17+
- Provides direct access to Workers runtime APIs and bindings
18+
- Supports Workers Assets, enabling you to build static sites, SPAs, and full-stack applications
19+
- Leverages Vite's hot module replacement for consistently fast updates
20+
- Supports `vite preview` for previewing your build output in the Workers runtime prior to deployment

‎src/content/docs/workers/vite-plugin/migrating-from-wrangler-dev.mdx‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
pcx_content_type: concept
3+
title: Migrating from wrangler dev
4+
head: []
5+
sidebar:
6+
order: 6
7+
description: Migrating from wrangler dev to the Vite plugin
8+
---
9+
10+
Migrating from `wrangler dev` is a simple process and you can follow the instructions in [Get started](../get-started/).
11+
There are a few key differences to highlight:
12+
13+
### Input and output Worker config files
14+
15+
In the Vite integration, your Worker config file (for example, `wrangler.toml`) is the input configuration and a separate output configuration is created as part of the build.
16+
This output file is a snapshot of your configuration at the time of the build and is modified to reference your build artifacts.
17+
It is the configuration that is used for preview and deployment.
18+
19+
### Redundant fields in the Wrangler config file
20+
21+
There are various options in the Worker config file that are ignored when using Vite, as they are either no longer applicable or are replaced by Vite equivalents.
22+
If these options are provided, then warnings will be printed to the console with suggestions for how to proceed.
23+
Examples where the Vite configuration should be used instead include `alias` and `define`.

‎src/content/docs/workers/vite-plugin/secrets.mdx‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
pcx_content_type: concept
3+
title: Secrets
4+
head: []
5+
sidebar:
6+
order: 5
7+
description: Using secrets with the Vite plugin
8+
---
9+
10+
import { PackageManagers, WranglerConfig } from "~/components";
11+
12+
Secrets can be provided to your Worker in local development using a [`.dev.vars`](/workers/configuration/secrets/#local-development-with-secrets) file. If you are using [Cloudflare Environments](../cloudflare-environments) then the relevant `.dev.vars` file will be selected. For example, `CLOUDFLARE_ENV=staging vite dev` will load `.dev.vars.staging` if it exists and fall back to `.dev.vars`.
13+
14+
:::note
15+
The `vite build` command copies the relevant `.dev.vars[.env-name]` file to the output directory. This is only used when running `vite preview` and is not deployed with your Worker.
16+
:::

0 commit comments

Comments
 (0)