Public Beta: Remote bindings in local development

[korinne]

Hi all 👋

We’re excited to introduce beta support for remote bindings for local development, allowing you to connect to deployed resources like R2 buckets and D1 databases – all while running your Worker code on your local machine. This means you can test your local code changes against real data and services, without the overhead of deploying for each iteration.

You can try out remote bindings for local development today with:

• Wrangler v4.20.3: Use the wrangler dev --x-remote-bindings command.
• The Cloudflare Vite Plugin: Refer to the documentation for how to enable in your Vite config.
• The Cloudflare Vitest Plugin: Refer to the documentation for how to enable in your Vitest config.

Example configuration

Remote bindings can be specified on a per-binding basis using experimental_remote: true.

// wrangler.jsonc
{
  "name": "my-worker",
  "compatibility_date": "$today",

  "r2_buckets": [
    {
      "bucket_name": "screenshots-bucket",
      "binding": "screenshots_bucket",
      "experimental_remote": true,
    },
  ],
}

Get started today by reviewing our documentation for remote bindings, with special attention to the recommended remote bindings and unsupported remote bindings.

Background

Bindings are a core part of Cloudflare Workers, allowing your Worker to access and perform operations against other Cloudflare resources (like KV namespaces, R2 buckets, D1 databases, Queues, Durable Objects, etc) without needing to manage secret keys and tokens. Unlike traditional environment variables (which are typically strings), bindings are live objects with methods you can call directly to perform actions. In your Worker code, these are accessed via the env object (such as env.MY_KV). Whether your code is running in production or running locally, your Worker code interacts with these bindings using the exact same API calls, like env.MY_KV.put(). The difference is whether those bindings are interacting with their deployed counterparts, or local simulations.

How bindings work in local development
When you run wrangler dev (or vite dev if using the Cloudflare Vite plugin), the Miniflare simulator boots up and executes your Worker code using the same runtime used in production, workerd . To make sure calls on bindings can succeed and behave as expected, Miniflare creates locally simulated resources that a call like env.MY_KV.put() can interact with.

However, this locally simulated KV is initially empty – you need to populate it with data. You can do this using Wrangler commands, but this manual process breaks down in real-world scenarios:

• What if your application relies on a massive dataset? For example, you could have millions of keys in KV. Replicating the entire dataset locally is impractical, and scripting a subset is time-consuming.
• What if your local dev setup needs to be perfectly in sync? Let’s say that your team stores feature flags in KV. If a teammate flips a feature flag in staging to test a change, your local setup won’t know about it.
• What if you’re trying to move fast? If you’re quickly prototyping a new idea, needing to stop and seed a local copy for every resource can add context switching and slow things down.

Previously, our answer to these problems was remote development (via wrangler dev --remote ), which uploads all of your Worker code to Cloudflare’s network so that you can test against real resources. However, wrangler dev --remote comes at the cost of a much slower development cycle: you need to wait for your entire Worker to get deployed to a remote environment just to see if your change works as expected. For most users, wrangler dev --remote is even more impractical than seeding local resources, since remote execution of your Worker can slow down the development loop.

Introducing: Remote bindings for local development

Remote bindings bring the best of both: the speed of local code execution with the realism of interacting with live, deployed resources. You can specify which bindings should connect to their deployed counterparts in Wrangler configuration, and when you start your local development server, all calls to that binding will be proxied to the remote resource.

This means:

• You no longer need to seed local resources with data. Just point your binding to its remote counterpart.
• You get a faster, more efficient development loop. Your code runs and reloads instantly on your local machine, while your binding calls are sent to the remote resource.
• You gain higher confidence when developing and testing: Some services rely on complex infrastructure that is difficult/or impossible to replicate locally (like Workers AI, Cloudflare Images, and Browser Rendering). Connecting directly to the remote service ensures that you’re testing against the exact same behavior and infrastructure that will run in production.

Workers for Platforms users can also configure experimental_remote:true in dispatch namespace binding definitions:

{
  "dispatch_namespaces": [
    {
      "binding": "DISPATCHER",
      "namespace": "testing",
      "experimental_remote":true,
	
    }
  ]
}

This allows you to run your dynamic dispatch Worker locally, while connecting it to your remote dispatch namespace binding. You can then test changes to your core dispatching logic against real, deployed user Workers.

Known limitations

• There are some unsupported remote bindings. If you have use-cases for anything on this list, please comment below or open an issue.
• Remote bindings for local development will only be supported in Workers, not in Pages.
• Remote bindings only work in local dev as an outbound proxy – this does not work for an external resource connecting to a locally running Worker.

Open Questions

• Does configuring this setting in the binding definition feel intuitive? We originally went back and forth on whether specifying that a binding should target the deployed resource should be configured in something like .dev.vars / .env , since you’re really overriding local dev behavior.

  • This could look like MY_R2=@r2_bucket:my_r2_preview_bucket_name
  • However, we weren’t sure if this made the mental model even more confusing about what a binding actually is (we’d be making it appear more like a connection string rather than a live object).

• Will configuring remote bindings in Wrangler config be difficult for teams? Since teams are often sharing Wrangler configuration, we can imagine that each developer might have different preferences for which bindings should connect remotely. Needing to remember to toggle experimental_remote back and forth before committing changes could get really tedious – another reason we thought about configuring this in something like .dev.vars / .env.

• For those building CLIs/develop tools for our platform: Some Workers for Platforms customers make CLIs either wrapping around Wrangler or custom, and we’d love to hear about your experience / if anything is missing from our documented API. Similarly, there are a number of developer tools building on our platform that want to provide a local dev experience, and would love to hear the ways in which you use our API for proxying remote connections during local dev.

Call to action

This is an early beta, and your feedback is critical to helping us refine the experience. After you've had a chance to try it out, please share your thoughts with us below on this discussion topic.

We are particularly interested in:

• Reporting any bugs or unexpected behavior you encounter. Please open an issue with as much detail as possible.

• Feedback on what you like about this workflow. Does it solve a real problem for you? What use-cases have you uncovered that we didn’t anticipate?

• Feedback on what rough edges we missed. Are there parts of the experience that feel confusing or could be improved?

• If you’d like to book time to give feedback to our team directly, we’d love to chat! Feel free to book any open time on my calendar.

[they-cloned-me]

Oh, this is gonna be lit🔥🔥

[celestial-rose]

This is ironically an amazing solution.
I say ironically because I just spent my whole night tweaking a copy of my prod db as a deployed "dev" D1 db binding and exclusively using --remote for it in local so I can have a remote binding.
I was so deep into this that by reading this discussion's title I was like "But isn't that already the case??"

AMAZING DELIVERY !!! And as always, thanks a million.

[danieljvdm]

- Unexpected fields found in r2_buckets[0] field:
  "experimental_remote"

Is this actually live? I'm on 4.20.3...

[dario-piotrowicz]

yes it should be live and working on 4.20.3

What are you running? wrangler dev? have you passed the --x-remote-bindings flag? 🙂

[flikteoh]

Getting the same when doing wrangler deploy

 ⛅️ wrangler 4.20.3
───────────────────
▲ [WARNING] Processing wrangler.jsonc configuration:

    - Unexpected fields found in r2_buckets[0] field: "experimental_remote"
    - Unexpected fields found in d1_databases[0] field: "experimental_remote"

[dario-piotrowicz]

Hi @flikteoh, I can confirm the issue with wrangler deploy, that's an oversight on our part, apologies for that 🙇

I started working on a fix that we should release soon: #9678

However those are warnings so it shouldn't break anything 🙂

[flikteoh]

Yeah I believe those were just oversight, same for wrangler tail.

Thanks for all the work guys!

[StephenHaney]

This is a great help for R2. Your problem statement in the background section describes our use case. And bonus, since we can stop using --remote we can now also use SQLite in DO.

Just to clarify, remote bindings do not support Durable Objects yet, correct? We definitely would also use DO remote bindings. Our local and PR preview environments share all of the same resources, so it's awkward when DO state mismatches between them and we need to re-seed PR previews. But the R2 solve is already great, since our PR Previews had lots of 404's from missing assets that were added in local dev.

[hkochniss]

Just a question that might have an obvious answer: If I want to switch between remote vs non-remote based on my local "environment", how would I do this?

I know with Vite plugin I can dynamically generate the vite config and therefor point to another wrangler.jsonc from vite.config.ts based on an VITE_ environment variable, but is there even some "hierarchical" wrangler.jsonc support or how would we switch only between "remote resources" and "local resources" with 2 different package.json scripts?

[dario-piotrowicz]

Hi @hkochniss thanks for the interest here! 🫶

I can think of a couple of ways of switching between remote and non-remove versions of the binding, one is simply by using environments, you simply declare you binding multiple times one per environment and then run wrangler dev -e <ENV_NAME>, alternatively you can also use different wrangler config files such as wrangler.a.jsonc, wrangler.b.jsonc and simply call wrangler dev -c <wrangler.a.json|wrangler.b.jsonc> to use either one of those.

Would any of the above help?

Since you emphasised "only" in your question I am guessing that you might like to have the exact same config file and basically turn on/off the binding's remote config? If that's the case no, I don't think that there is currently any clean way to do that, but I also couldn't imagine a clean API for that either (keeping in mind that bindings are non-inheritable), do you have any API/DX in mind?

[hkochniss]

ah thanks, forgot about the environments feature in wrangler.jsonc, which basically (as I understand it?) allows you to just set the experimental_remote flag to true and keep the original binding settings?

That seems very clean and is "close to" the original config, seems like the best solution. 👍🏻

[dario-piotrowicz]

allows you to just set the experimental_remote flag to true and keep the original binding settings?

No, as I mentioned bindings are non-inheritable so you can't simply override the flag but you need to re-define the binding in each environment in your wrangler.jsonc 😓

[hkochniss]

well, close enough, not ideal but maintainable IMO

[korinne]

@hkochniss Would you be open to chatting about your ideal setup for environments <> remote bindings? Would love to talk more. You can book time on my cal directly, if that works: https://calendar.app.google/8PitCfc1hhYiteZw8

[BeiXiao]

Did support tanstack start? I tried modifying vite.config.ts and used @cloudflare/vite-plugin in it, but it didn't work. Does @cloudflare/vite-plugin only support React Router 7?

[dario-piotrowicz]

Hi @BeiXiao 🙂👋

This is a discussion for remote bindings, for different issues/questions please open separate discussions/issues in the general repository 🙂

It's also worth looking for pre-existing discussions/issues for the specific topic you're interested in, regarding tenstack this might be pertinent? #9622

[BeiXiao]

Hi there, I'm asking about how to set up remote binding in TanStack Start.

[dario-piotrowicz]

Ok sorry, your earlier message sounded like a generic one, what issue are you facing?

If you could share a minimal reproduction of the issue I'd be happy to have a look 🙂

Anyways, unless TenStack Start does something specific to bindings, remote bindings should work with the vite plugin regardless of the framework in use.

[orenmizr]

trying to make this work is killing my soul. #9887 (comment)

[ChrisTalman]

This is really great!

Do you have a rough sense when Hyperdrive will become available as a remote binding? I see that the documentation says it is 'being actively worked on'.

And will this mean that, when I have a worker running on my local machine, the database connection within it will be (1) fully SSL-enabled between my local machine and the Cloudflare servers, and then (2) fully SSL-enabled from the Cloudflare servers to the database itself?

[medreseli]

Documentation needs to updated.
Remote binding are working with wrangler dev but they are not working with vite dev.

[orenmizr]

really ? it now works for you ? my setup: nuxt server + local workers + kv + remote worker ai + vectorize fails everytime. they can't see each other bindings like the context is not being shared. what version are you working on ?

[medreseli]

I could not understand the issue you are facing but, you can use wrangler dev command to try your worker locally with remote bindings. I am using Vite + React TS in my project. You need to build your project first then run wrangler dev to try it. Unfortunately, wrangler dev does not do HMR. You first develop your project with Vite then use Wrangler to see how it works with remote bindings.

[orenmizr]

i have been using wrangler dev. tried with vite or cloudflare dev module. the issue was the the KV could not communicate to all workers (nuxt server like your next, local workers, and 2 remote workers ai+vectorize). it is meant to put all in the same context but failed to so. so some pub events and other could not see nad sub.

i figured that issue has been fixed by reading your post.

[rdvo]

confirme works with wrangler dev but then you cant do HMT/quick reload change gotta re-build and run dev after every change

[rdvo]

ya im using a SPA react app with hono template and npm run dev doesnt work with rmeote bindings, i can do npx wrangler dev and it works but then the. SPA is messed up

Using cloudflare vite plugin

[lrapoport-cf]

hi @rdvo :) would you be able to open an issue so we can help troubleshoot?

[MattieTK]

@rdvo thanks for flagging, we identified this on Twitter to be an old version of @cloudflare/vite-plugin which didn't cover these cases. Updating the plugin version to the latest solved the problem.

[orenmizr]

i threw hours of claude agents on this and opened an issue before.

• running "wrangler dev" on you next will create more issues and will fail unexpectedly. i tried it with nuxt.
• for nuxt : there are 2 way to config : a vite config or a nitro dev module. they are supposed to connect you code via bindings.
  -- the nitro module is not being actively developed. it seems. the ai patched it in the node modules (added a correct way to add remote binding true, probably seen it in research)
  -- the vite config failed to keep all workers under one bindings.

i ended simplifying the workers architecture until someone can make next/nuxt work with local workers + local Kv + remote AI/Vectorize.

so far. did not find anyone who claims to have succeeded in this.

[lrapoport-cf]

hi @orenmizr :) is this the same issue as you previously reported here: #9887? if so, could you please provide a reproduction so we can help troubleshoot? thanks!

[orenmizr]

my issues with local dev remote goes beyond just queues... a lot of other bindings failed and caused me to change rethink workarounds.