You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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).
12
+
## Local development with Wrangler
13
+
14
+
The [Wrangler CLI](/workers/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 Workers 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).
13
15
14
16
:::note
15
17
@@ -29,35 +31,34 @@ This command runs your Worker code locally, allowing you to test changes in real
29
31
30
32
---
31
33
32
-
<Renderfile="bindings_per_env" />
34
+
## Working with local data
33
35
34
-
## Work with localdata
36
+
When you run `wrangler dev`, Wrangler automatically creates local versions of your resources (like KV, D1, or R2). This means you **don’t** need to manually set up separate local instances for each service. However, newly created local resources **won’t** contain any data — you'll need to use Wrangler commands with the `--local` flag to populate them. Changes made to local resources won’t affect production data.
35
37
36
-
When running `wrangler dev`, resources such as KV, Durable Objects, D1, and R2 will be stored and persisted locally and not affect the production resources.
38
+
By default, local data resides in the `.wrangler/state` folder. You can delete this folder at any time to reset your local environment, and Wrangler will recreate it the next time you run `wrangler dev`.
[Wrangler](/workers/wrangler/) will automatically create local versions of bindings found in the [Wrangler configuration file](/workers/wrangler/configuration/). These local resources will not have data in them initially, so you will need to add data manually via Wrangler commands and the [`--local` flag](#use---local-flag).
44
+
/>
41
45
42
-
When you run `wrangler dev` Wrangler stores local resources in a `.wrangler/state` folder, which is automatically created.
46
+
### Changing the local data directory
43
47
44
-
If you prefer to specify a directory, you can use the [`--persist-to`](/workers/wrangler/commands/#dev) flag with `wrangler dev` like this:
48
+
If you prefer to specify a different directory for local storage, use the [`--persist-to`](/workers/wrangler/commands/#dev) flag with `wrangler dev`:
45
49
46
50
<PackageManagers
47
51
type="exec"
48
52
pkg="wrangler"
49
53
args="dev --persist-to <DIRECTORY>"
50
54
/>
51
55
52
-
Using this will write all local storage and cache to the specified directory instead of `.wrangler`.
53
-
54
56
:::note
55
-
56
-
This local persistence folder should be added to your `.gitignore` file.
57
+
The local persistence folder (like `.wrangler/state` or any custom folder you set) should be added to your `.gitignore` to avoid committing local development data to version control.
57
58
58
59
:::
59
60
60
-
### Use`--local` flag
61
+
### Using the`--local` flag
61
62
62
63
The following [Wrangler commands](/workers/wrangler/commands/) have a `--local` flag which allows you to create, update, and delete local data during development:
63
64
@@ -68,42 +69,73 @@ The following [Wrangler commands](/workers/wrangler/commands/) have a `--local`
If using `--persist-to` to specify a custom folder with `wrangler dev` you should also add `--persist-to` with the same directory name along with the `--local` flag when running the commands above. For example, to put a custom KV key into a local namespace via the CLI you would run:
72
+
<Detailsheader="Using `--local` with `--persist-to`">
73
+
If you run `wrangler dev --persist-to <DIRECTORY>` to specify a custom location for local data, you must also include the same `--persist-to <DIRECTORY>` when running other Wrangler commands that modify local data (and be sure to include the `--local` flag).
74
+
75
+
For example, to create a KV key named `test` with a value of `12345` in a local KV namespace, run:
72
76
73
77
<PackageManagers
74
78
type="exec"
75
79
pkg="wrangler"
76
80
args="kv key put test 12345 --binding MY_KV_NAMESPACE --local --persist-to worker-local"
77
81
/>
78
82
79
-
Running `wrangler kv key put` will create a new key `test` with a value of `12345` on the local namespace specified via the binding `MY_KV_NAMESPACE` in the [Wrangler configuration file](/workers/wrangler/configuration/). This example command sets the local persistence directory to `worker-local` using `--persist-to`, to ensure that the data is created in the correct location. If `--persist-to` was not set, it would create the data in the `.wrangler` folder.
83
+
This command:
84
+
85
+
- Sets the KV key `test` to `12345` in the binding `MY_KV_NAMESPACE` (defined in your [Wrangler configuration file](/workers/wrangler/configuration/)).
86
+
- Uses `--persist-to worker-local` to ensure the data is created in the **worker-local** directory instead of the default `.wrangler/state`.
87
+
- Adds the `--local` flag, indicating you want to modify local data.
88
+
89
+
If `--persist-to` is not specified, Wrangler defaults to using `.wrangler/state` for local data.
90
+
91
+
</Details>
80
92
81
93
### Clear Wrangler's local storage
82
94
83
-
If you need to clear local storage entirely, delete the `.wrangler/state` folder. You can also be more fine-grained and delete specific resource folders within `.wrangler/state`.
95
+
To reset or remove local storage:
96
+
97
+
- Delete the entire `.wrangler/state` folder, or
98
+
- Delete specific sub-folders within `.wrangler/state` for more targeted clean-up.
84
99
85
-
Any deleted folders will be created automatically the next time you run `wrangler dev`.
100
+
Any folders you remove will be automatically re-created the next time you run `wrangler dev`.
86
101
87
-
## Local-only environment variables
102
+
###Local-only secrets and environment variables
88
103
89
-
When running `wrangler dev`, variables in the [Wrangler configuration file](/workers/wrangler/configuration/) are automatically overridden by values defined in a `.dev.vars` file located in the root directory of your worker. This is useful for providing values you do not want to check in to source control.
104
+
The [`.dev.vars` file](/workers/configuration/secrets/#local-development-with-secrets) is primarily intended for defining **local secrets** that you do not want to commit to source control. Any environment variables declared in `.dev.vars` will override matching variables in your [Wrangler configuration file](/workers/wrangler/configuration/)**when running `wrangler dev`**.
105
+
106
+
For example, if you want to test local credentials or mock a production API endpoint:
90
107
91
108
```shell
92
-
API_HOST = "localhost:4000"
93
-
API_ACCOUNT_ID = "local_example_user"
109
+
API_HOST="localhost:4000"
110
+
API_ACCOUNT_ID="local_example_user"
94
111
```
95
112
96
-
## Develop using remote resources and bindings
113
+
:::note
114
+
Since `.dev.vars` is loaded only when running `wrangler dev`, these values do not affect your production environment. Make sure to add `.dev.vars` to your `.gitignore` so you don’t accidentally commit sensitive credentials to version control.
115
+
:::
116
+
117
+
To learn about setting up environment variables for other non-local environments (such as staging or production), look into [Wrangler Environments](/wrangler/environments/#staging-and-production-environments).
118
+
119
+
## Working with remote data
97
120
98
-
There may be times you want to develop against remote resources and bindings. To run `wrangler dev` in remote mode, add the `--remote`flag, which will run both your code and resources remotely:
121
+
Sometimes you need to test your Worker against real Cloudflare resources (for example, to ensure accurate data or environment parity). In this case, use the `wrangler dev --remote`command:
For some products like KV and R2, remote resources used for `wrangler dev --remote` must be specified with preview ID/names in the [Wrangler configuration file](/workers/wrangler/configuration/) such as `preview_id` for KV or `preview_bucket name` for R2. Resources used for remote mode (preview) can be different from resources used for production to prevent changing production data during development. To use production data in `wrangler dev --remote`, set the preview ID/name of the resource to the ID/name of your production resource.
125
+
### Preview vs. Production Resources
126
+
127
+
For certain services, like KV and R2, **remote** development (`wrangler dev --remote`) requires specifying **preview** IDs or names in your [Wrangler configuration file](/workers/wrangler/configuration/). For example:
128
+
129
+
- KV uses `preview_id`
130
+
- R2 uses `preview_bucket`
131
+
132
+
By default, these **preview** resources can be different from your production resources, letting you develop safely without modifying live data. If you do need to work with production data while using `wrangler dev --remote`, simply set the preview ID or name to match your production resource’s ID or name.
133
+
134
+
<Renderfile="bindings_per_env" />
103
135
104
136
## Customize `wrangler dev`
105
137
106
-
You can customize how `wrangler dev`works to fit your needs. Refer to [the `wrangler dev` documentation](/workers/wrangler/commands/#dev) for available configuration options.
138
+
You can further customize the behavior of `wrangler dev`(for instance, by changing ports or skipping Wrangler's build steps). Refer to [the `wrangler dev` documentation](/workers/wrangler/commands/#dev) for available configuration options.
Copy file name to clipboardExpand all lines: src/content/partials/workers/bindings_per_env.mdx
+12-13Lines changed: 12 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,45 +2,44 @@
2
2
{}
3
3
---
4
4
5
-
### Binding Support: Local vs. Remote Development
5
+
##Supported bindings in local and remote dev
6
6
7
-
#### Local Development
7
+
-**Local Development:** Includes [`wrangler dev`](/workers/wrangler/commands/#dev) (without the `--remote` flag) and the [Cloudflare Vite plugin](/local-development/vite/). This mode simulates the Cloudflare Workers environment locally.
8
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.
9
+
-**Remote Development:** 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. There is no Vite plugin equivalent for testing remote resources.
¹ 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.
31
+
[^1]: Using Workers AI always accesses your Cloudflare account in order to run AI models and will incur usage charges, even in local development.
32
+
33
+
[^2]: Using Hyperdrive with local development allows you to connect to a local database (running on `localhost`) but you cannot connect to a remote database. To connect to a remote database, use `wrangler dev --remote`.
34
+
35
+
[^3]: Using Vectorize always accesses your Cloudflare account to run queries, and will incur usage charges even in local development.
37
36
38
37
> **Tip:** If you need to use any bindings marked with ❌ under local development, run:
39
38
>
40
39
> ```bash
41
40
> wrangler dev --remote
42
41
>```
43
42
>
44
-
> This uploads your code to Cloudflare so you can test those bindings against the real environment.
43
+
> This command allows you to develop against remote resources and data stored on Cloudflare's network.
0 commit comments