Local development

Cloudflare Workers and most connected resources can be fully developed and tested locally - providing confidence that the applications you build locally will work the same way in production. This allows you to be more efficient and effective by providing a faster feedback loop and removing the need to test against remote resources. Local development runs against the same production runtime used by Cloudflare Workers, workerd Open external link .

In addition to testing Workers locally with wrangler dev, the use of Miniflare allows you to test other Developer Platform products locally, such as R2, KV, D1, and Durable Objects.

​​ Start a local development server

Wrangler provides a 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:

$ npx wrangler dev

wrangler dev will run the Worker directly on your local machine. wrangler dev uses a combination of workerd and Miniflare Open external link , a simulator that allows you to test your Worker against additional resources like KV, Durable Objects, WebSockets, and more.

​​ Supported resource bindings in different environments

With any bindings that are not supported locally, you will need to use the --remote command in wrangler, such as wrangler dev --remote.

​​ Work with local data

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.

​​ Use bindings in wrangler.toml

Wrangler will automatically create local versions of bindings found in the wrangler.toml configuration file. 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.

When you run wrangler dev Wrangler stores local resources in a .wrangler/state folder, which is automatically created.

If you prefer to specify a directory, you can use the --persist-to flag with wrangler dev like this:

$ npx wrangler dev --persist-to <DIRECTORY>

Using this will write all local storage and cache to the specified directory instead of .wrangler.

​​ Use --local flag

The following Wrangler commands have a --local flag which allows you to create, update, and delete local data during development:

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:

$ npx wrangler kv:key put test 12345 --binding MY_KV_NAMESPACE --local --persist-to worker-local

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 wrangler.toml. 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.

​​ Clear Wrangler’s local storage

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.

Any deleted folders will be created automatically the next time you run wrangler dev.

​​ Develop using remote resources and bindings

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:

$ npx wrangler dev --remote

For some products like KV and R2, remote resources used for wrangler dev --remote must be specified with preview ID/names in wrangler.toml 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.

​​ Customize wrangler dev

You can customize how wrangler dev works to fit your needs. Refer to the wrangler dev documentation for available configuration options.

​​ Related resources

• D1 local development - The official D1 guide to local development and testing.
• Debugging tools - Tools to help you diagnose issues and gain insight into your Workers.