Skip to content

Commit 0c9b53d

Browse files
korinnekorinne
committed
Adds guidance for when to use Wrangler vs Vite, adds Vite to the binding comparison
1 parent 66508f7 commit 0c9b53d

File tree

3 files changed

+70
-31
lines changed

3 files changed

+70
-31
lines changed

‎src/content/docs/workers/local-development/index.mdx‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,26 @@ You can test changes locally using the following:
1313

1414
- **Wrangler’s built-in dev command** [`wrangler dev`](/workers/wrangler/commands/#dev), which uses [`workerd`](https://github.com/cloudflare/workerd) and Miniflare to simulate production behavior and resource bindings locally. Wrangler also offers the option to [develop against remote resources](/workers/local-development/wrangler/#develop-using-remote-resources-and-bindings) with `wrangler dev --remote`, allowing you to test directly with data stored on Cloudflare's network.
1515

16-
- The **Cloudflare Vite plugin** (`@cloudflare/vite-plugin`), which integrates directly with [Vite](https://vite.dev/) and runs your code in the [Worker Runtime](/workers/reference/how-workers-works/) ([`workerd`](https://github.com/cloudflare/workerd)), while also offering features like [hot module replacement (HMR)](https://vite.dev/guide/features.html#hot-module-replacement). The Vite plugin is currently in open beta.
16+
- The **Cloudflare Vite plugin** (`@cloudflare/vite-plugin`), which integrates directly with [Vite](https://vite.dev/) and runs your code in the [Worker Runtime](/workers/reference/how-workers-works/) ([`workerd`](https://github.com/cloudflare/workerd)), while also offering features like [hot module replacement (HMR)](https://vite.dev/guide/features.html#hot-module-replacement). The Vite plugin is currently in **open beta**.
1717

1818
Both approaches aim to provide confidence that your local environment will closely match the production runtime, removing the need to [test against remote resources](#develop-using-remote-resources-and-bindings).
19+
20+
## Choosing Between Wrangler and the Vite Plugin
21+
22+
When you are building with Cloudflare Workers, choosing between Wrangler and the Cloudflare Vite plugin primarily depends on your project’s scope and development workflow. Below are some guidelines to help you decide which toolset to use.
23+
24+
### When to use Wrangler
25+
26+
- **Backend and Workers-focused development:** Ideal if your primary goal is to build serverless functions, APIs, or other background tasks that need to closely resemble production behavior. Wrangler provides the most accurate local simulation of Cloudflare’s runtime.
27+
28+
- **Testing with real Cloudflare resources:** If you need to verify interactions with actual Cloudflare data or services, Wrangler’s `--remote` flag lets you test in a production-like environment without deploying your app fully to production.
29+
30+
- **Limited frontend requirements:** Wrangler is well suited for simple or minimal frontend needs, where complex bundling and advanced development features (like Hot Module Replacement) are not critical.
31+
32+
### When to use the Cloudflare Vite Plugin
33+
34+
- **Frontend-intensive developmentL** If your application relies heavily on modern frontend [frameworks](/workers/frameworks/) — such as React, Vue, Svelte, or Solid — the Vite plugin makes setup and configuration straightforward.
35+
36+
- **Rapid iteration with HMR:** Hot Module Replacement (HMR) provides near-instant reloads whenever you make changes. This speeds up development by letting you see updates in the browser without a full page refresh.
37+
38+
- **Advanced frontend optimizations**: The Vite plugin supports tree-shaking, code splitting, efficient bundling, CSS handling, and caching strategies. If you require optimized frontend delivery — especially for large or complex UIs — Vite is a strong fit.

‎src/content/docs/workers/local-development/wrangler.mdx‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ description: Locally develop and test changes with `wrangler dev`
99

1010
import { Render, PackageManagers } from "~/components";
1111

12-
## Start a local development server
12+
Wrangler provides a [`dev`](/workers/wrangler/commands/#dev) command that starts a local development server directly on your machine. It uses a combination of the Worker Runtime (`workerd`) and [Miniflare](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare), a simulator that allows you to test your Worker against additional resources like [R2](/r2/), [KV](/kv), [D1](/d1), and [Durable Objects](/durable-objects).
1313

1414
:::note
1515

@@ -19,11 +19,15 @@ Users new to Wrangler CLI and Cloudflare Workers should visit the [Wrangler Inst
1919

2020
:::
2121

22-
Wrangler provides a [`dev`](/workers/wrangler/commands/#dev) command that starts a local server for developing your Worker. Make sure you have `npm` installed and run the following in the folder containing your Worker application:
22+
## Start a local development server
23+
24+
To start a local development server for your Worker, navigate to your Worker’s project folder and run:
2325

2426
<PackageManagers type="exec" pkg="wrangler" args="dev" />
2527

26-
`wrangler dev` will run the Worker directly on your local machine. `wrangler dev` uses a combination of `workerd` and [Miniflare](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare), a simulator that allows you to test your Worker against additional resources like KV, Durable Objects, WebSockets, and more.
28+
This command runs your Worker code locally, allowing you to test changes in real time. By default, it will store local data in a `.wrangler/state` folder in your project directory.
29+
30+
---
2731

2832
<Render file="bindings_per_env" />
2933

‎src/content/partials/workers/bindings_per_env.mdx‎

Lines changed: 42 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,45 @@
22
{}
33
---
44

5-
### Supported resource bindings in different environments
6-
7-
| Product | Local Dev Supported | Remote Dev Supported |
8-
| ----------------------------------- | ------------------- | -------------------- |
9-
| AI | ✅[^1] | ✅ |
10-
| Assets | ✅ | ✅ |
11-
| Analytics Engine | ✅ | ✅ |
12-
| Browser Rendering | ❌ | ✅ |
13-
| D1 | ✅ | ✅ |
14-
| Durable Objects | ✅ | ✅ |
15-
| Email Bindings | ❌ | ✅ |
16-
| Hyperdrive | ✅ | ✅ |
17-
| Images | ✅ | ✅ |
18-
| KV | ✅ | ✅ |
19-
| mTLS | ❌ | ✅ |
20-
| Queues | ✅ | ❌ |
21-
| R2 | ✅ | ✅ |
22-
| Rate Limiting | ✅ | ✅ |
23-
| Service Bindings (multiple Workers) | ✅ | ✅ |
24-
| Vectorize | ✅[^2] | ✅ |
25-
| Workflows | ✅ | ❌ |
26-
27-
With any bindings that are not supported locally, you will need to use the [`--remote` command](#develop-using-remote-resources-and-bindings) in wrangler, such as `wrangler dev --remote`.
28-
29-
[^1]: Using Workers AI always accesses your Cloudflare account in order to run AI models and will incur usage charges even in local development.
30-
31-
[^2]: Using Vectorize always accesses your Cloudflare account to run queries, and will incur usage charges even in local development.
5+
### Binding Support: Local vs. Remote Development
6+
7+
#### Local Development
8+
9+
Includes [Wrangler `dev`](/workers/wrangler/commands/#dev) without `--remote` and the [Cloudflare Vite plugin](/local-development/vite/). This mode simulates the Cloudflare Workers environment locally.
10+
11+
#### Remote Development
12+
13+
Uses [Wrangler `dev --remote`](/workers/wrangler/commands/#dev)), deploying your code to Cloudflare’s infrastructure during development. This ensures all bindings and resources match production conditions.
14+
15+
| Binding | Local (Wrangler & Vite) | Remote (Wrangler only) |
16+
| --------------------------------------- | :---------------------: | :--------------------: |
17+
| **AI** | ✅¹ | ✅ |
18+
| **Assets** | ✅ | ✅ |
19+
| **Analytics Engine** | ✅ | ✅ |
20+
| **Browser Rendering** | ❌ | ✅ |
21+
| **D1** | ✅ | ✅ |
22+
| **Durable Objects** | ✅ | ✅ |
23+
| **Email Bindings** | ❌ | ✅ |
24+
| **Hyperdrive** | ✅ | ✅ |
25+
| **Images** | ✅ | ✅ |
26+
| **KV** | ✅ | ✅ |
27+
| **mTLS** | ❌ | ✅ |
28+
| **Queues** | ✅ | ❌ |
29+
| **R2** | ✅ | ✅ |
30+
| **Rate Limiting** | ✅ | ✅ |
31+
| **Service Bindings (multiple Workers)** | ✅ | ✅ |
32+
| **Vectorize** | ✅² | ✅ |
33+
| **Workflows** | ✅ | ❌ |
34+
35+
¹ Using Workers AI always accesses your Cloudflare account to run AI models, incurring usage charges even during local development.
36+
² Using Vectorize always accesses your Cloudflare account to run queries, incurring usage charges even during local development.
37+
38+
> **Tip:** If you need to use any bindings marked with ❌ under local development, run:
39+
>
40+
> ```bash
41+
> wrangler dev --remote
42+
> ```
43+
>
44+
> This uploads your code to Cloudflare so you can test those bindings against the real environment.
45+
46+
---

0 commit comments

Comments
 (0)