Text of developers.cloudflare.com › workers › local-development as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Local development · Cloudflare Workers docs

Skip to content Documentation Index Fetch the complete documentation index at: https://developers.cloudflare.com/workers/llms.txt Use this file to discover all available pages before exploring further. Local development You can build, run, and test your Worker code on your own local machine before deploying it to Cloudflare's network. This is made possible through Miniflare , a simulator that executes your Worker code in a local workerd ↗︎ process. workerd also powers the hosted Workers platform.

By default , your Worker's bindings connect to locally simulated resources , but can be configured to interact with the real, production resource with remote bindings . Security considerations Core concepts Worker execution vs Bindings When developing Workers, it's important to understand two distinct concepts: Worker execution : Where your Worker code actually runs (on your local machine vs on Cloudflare's infrastructure).

Bindings : How your Worker interacts with Cloudflare resources (like KV namespaces , R2 buckets , D1 databases , Queues , Durable Objects , etc). In your Worker code, these are accessed via the env object (such as env.MY_KV ). Start a local development server You can start a local development server using: The Cloudflare Workers CLI Wrangler , using the built-in wrangler dev command. npx wrangler dev yarn wrangler dev pnpm wrangler dev Vite ↗︎ , using the Cloudflare Vite plugin . npx vite dev yarn vite dev pnpm vite dev Both Wrangler and the Cloudflare Vite plugin use Miniflare under the hood, and are developed and maintained by the Cloudflare team.

For guidance on choosing when to use Wrangler versus Vite, see our guide Choosing between Wrangler & Vite . Get started with Wrangler Get started with the Cloudflare Vite plugin Inbound TCP and gRPC To receive raw TCP connections locally, export a connect() handler and configure a TCP listener in wrangler.jsonc : { "connect" : [{ "protocol" : "tcp" , "port" : 8788 }], } [[ connect ]] protocol = "tcp" port = 8_788 Connect TCP or gRPC clients to localhost:8788 .

The port comes from this configuration; exporting the handler alone does not create a listener. Refer to Bidirectional gRPC with Workers and Containers for an example that uses the local TCP listener to test a gRPC server running in a Container. Defaults By default, running wrangler dev / vite dev (when using the Vite plugin ) means that: Your Worker code runs on your local machine. All resources your Worker is bound to in your Wrangler configuration are simulated locally.

The local workerd runtime runs with TZ=UTC so that Date and Intl APIs inside your Worker observe UTC, matching the production Cloudflare runtime regardless of your machine's timezone. Bindings during local development Bindings are interfaces that allow your Worker to interact with various Cloudflare resources (like KV namespaces , R2 buckets , D1 databases , Queues , Durable Objects , etc). In your Worker code, these are accessed via the env object (such as env.MY_KV ).

During local development, your Worker code interacts with these bindings using the exact same API calls (such as env.MY_KV.put() ) as it would in a deployed environment. These local resources are initially empty, but you can populate them with data, as documented in Adding local data . By default, bindings connect to local resource simulations (except for AI bindings , as AI models always run remotely). You can override this default behavior and connect to the remote resource on a per-binding basis with remote bindings .

This lets you connect to real, production resources while still running your Worker code locally. When using wrangler dev , you can temporarily disable all remote bindings (and connect only to local resources) by providing the --local flag (i.e. wrangler dev --local ) Remote bindings Remote bindings are bindings that are configured to connect to the deployed, remote resource during local development instead of the locally simulated resource.

Remote bindings are supported by Wrangler , the Cloudflare Vite plugin , and the @cloudflare/vitest-plugin package. You can configure remote bindings by setting remote: true in the binding definition. Example configuration { "name" : "my-worker" , // Set this to today's date "compatibility_date" : "2026-11-20" , "r2_buckets" : [ { "bucket_name" : "screenshots-bucket" , "binding" : "screenshots_bucket" , "remote" : true , }, ], } name = "my-worker" # Set this to today's date compatibility_date = "2026-11-20" [[ r2_buckets ]] bucket_name = "screenshots-bucket" binding = "screenshots_bucket" remote = true When remote bindings are configured, your Worker still executes locally , only the underlying resources your bindings connect to change.

For all bindings marked with remote: true , Miniflare will route its operations (such as env.MY_KV.put() ) to the deployed resource. All other bindings not explicitly configured with remote: true continue to use their default local simulations. Integration with environments Remote Bindings work well together with Workers Environments . To protect production data, you can create a development or staging environment and specify different resources in your Wrangler configuration than you would use for production.

For example: { "name" : "my-worker" , // Set this to today's date "compatibility_date" : "2026-11-20" , "env" : { "production" : { "r2_buckets" : [ { "bucket_name" : "screenshots-bucket" , "binding" : "screenshots_bucket" , }, ], }, "staging" : { "r2_buckets" : [ { "bucket_name" : "preview-screenshots-bucket" , "binding" : "screenshots_bucket" , "remote" : true , }, ], }, }, } name = "my-worker" # Set this to today's date compatibility_date = "2026-11-20" [[ env . production . r2_buckets ]] bucket_name = "screenshots-bucket" binding = "screenshots_bucket" [[ env . staging . r2_buckets ]] bucket_name = "preview-screenshots-bucket" binding = "screenshots_bucket" remote = true Running wrangler dev -e staging (or CLOUDFLARE_ENV=staging vite dev ) with the above configuration means that: Your Worker code runs locally All calls made to env.screenshots_bucket will use the preview-screenshots-bucket resource, rather than the production screenshots-bucket .

Recommended remote bindings We recommend configuring specific bindings to connect to their remote counterparts. These services often rely on Cloudflare's network infrastructure or have complex backends that are not fully simulated locally. The following bindings are recommended to have remote: true in your Wrangler configuration: Browser Run : To interact with a real headless browser for rendering. There is no current local simulation for Browser Run. { "browser" : { "binding" : "MY_BROWSER" , "remote" : true }, } [ browser ] binding = "MY_BROWSER" remote = true Workers AI : To utilize actual AI models deployed on Cloudflare's network for inference.

There is no current local simulation for Workers AI. { "ai" : { "binding" : "AI" , "remote" : true }, } [ ai ] binding = "AI" remote = true Vectorize : To connect to your production Vectorize indexes for accurate vector search and similarity operations. There is no current local simulation for Vectorize. { "vectorize" : [ { "binding" : "MY_VECTORIZE_INDEX" , "index_name" : "my-prod-index" , "remote" : true } ], } [[ vectorize ]] binding = "MY_VECTORIZE_INDEX" index_name = "my-prod-index" remote = true mTLS : To verify that the certificate exchange and validation process work as expected.

There is no current local simulation for mTLS bindings. { "mtls_certificates" : [ { "binding" : "MY_CLIENT_CERT_FETCHER" , "certificate_id" : "<YOUR_UPLOADED_CERT_ID>" , "remote" : true } ] } [[ mtls_certificates ]] binding = "MY_CLIENT_CERT_FETCHER" certificate_id = "<YOUR_UPLOADED_CERT_ID>" remote = true Images : To connect to a high-fidelity version of the Images API, and verify that all transformations work as expected.

Local simulation for Cloudflare Images is limited with only a subset of features . { "images" : { "binding

The rest of this page is on the live site.