This bridge makes it possible to interact with remote Cloudflare Workers bindings(like KV, D1, etc...) from anywhere you want.

For example,

• Use remote data with Vite based meta frameworks local development
• CLI tools to sync remote data to local, copy remote data to remote
• Static Site Generation, Pre-rendering with remote data
• etc...

Many possibilities are unlocked now! 🔓

To understand the motivation in detail, see also my talk slides.

This bridge has 2 components.

• Module: Mock module to be imported into your application
  • written as pure ESM
  • run on any environment
• Worker: Proxy worker to be invoked by the bridge module
  • hosted by wrangler dev or unstable_dev() in advance
  • run on Cloudflare Workers environment

Bridge module itself is platform agnostic, you can use it on any platform|environment.

Install bridge as usual.

npm install -D cfw-bindings-wrangler-bridge

And make sure to prepare wrangler.toml for your needs.

There are 2 options.

• 🅰️ Bridge worker w/ external wrangler dev process
• 🅱️ Bridge worker w/ unstable_dev() API by wrangler package

It's up to your usecase.

wrangler dev ./path/to/node_modules/cfw-bindings-wrangler-bridge/worker/index.js --remote
# Worker will be running on `http://127.0.0.1:8787` by default

Of course you can interact with local environment by omitting --remote. All the other options(like --port, --persist-to) are also available.

Then, create bridge modules and use them anywhere in your code.

import { KVNamespace$ } from "cfw-bindings-wrangler-bridge";

// Default is bound to `http://127.0.0.1:8787`
const MY_KV = new KVNamespace$("MY_KV");
// Or specify origin
// const MY_KV = new KVNamespace$("MY_KV", {
//   bridgeWorkerOrigin: "http://localhsot:8686",
// });

// ✌️ This is remote KV!
await MY_KV.put("foo", "bar");
await MY_KV.get("foo"); // "bar"

This is isomorphoc approach, your module can be run on everywhere(Node.js, Bun, Browsers, etc).

Setups can be done in synchronous, it keeps your code as simple as possible.

You need to npm install -D warngler and create UnstableDevWorker instance.

import { unstable_dev } from "wrangler";
import { KVNamespace$ } from "cfw-bindings-wrangler-bridge";

const worker = await unstable_dev(
  "./path/to/node_modules/cfw-bindings-wrangler-bridge/worker/index.js",
  {
    local: false,
    // config: "./path/to/your/wrangler.toml",
    experimental: { disableExperimentalWarning: true },
  },
);

const MY_KV = new KVNamespace$("MY_KV", {
  bridgeWorkerOrigin: `http://${worker.address}:${worker.port}`,
});

// ✌️ This is remote KV!
await MY_KV.put("foo", "bar");
await MY_KV.get("foo"); // "bar"

// DO NOT FORGET...
await worker.stop();

This is Node.js only option since wrangler package depends on Node.js but may be handy for some cases.

It requires asynchronous style APIs for setup and dev worker should be managed by yourself.

Create multiple module instances automatically by getBindings() helper.

import { getBindings } from "cfw-bindings-wrangler-bridge";

const env = await getBindings<{
  TODOS: KVNamespace;
  SESSIONS: KVNamespace;
}>();

const user = await env.SESSIONS.get("abc", "json");
const todos = await env.TODOS.get(user.id);

Mixing local and remote service bindings is now possible.

cloudflare/workers-sdk#1182

import { Fetcher$ } from "cfw-bindings-wrangler-bridge";

const AUTH_SERVICE = new Fetcher$("AUTH", {
  bridgeWorkerOrigin: "http://127.0.0.1:3000",
});
const CART_SERVICE = new Fetcher$("CART", {
  bridgeWorkerOrigin: "http://127.0.0.1:4000",
});

Any type of bindings can be mixed with local and remote.

import { unstable_dev } from "wrangler";
import { R2Bucket$, KVNamespace$ } from "cfw-bindings-wrangler-bridge";

const prodWorker = await unstable_dev(/* ... */);

// Use remote
const PROD_ASSETS = new R2Bucket$("ASSETS", {
  bridgeWorkerOrigin: `http://${prodWorker.address}:${prodWorker.port}`,
});
// Use local
const DEV_KV = new KVNamespace$("SNAPSHOTS");

More to come...? PRs are welcome! 😉

The instances and values available from this bridge are not 100% compatible.

For example,

• Binding instances
  • The class constructors like KVNamespace, R2Object(aka HeadResult) are not publicly exposed
• Enumerable instance properties
  • Read-only properties are emulated by simple implementation
  • Some private properties and methods are included
• Exception
  • Not a specific error like TypeError, but just an Error
• etc...

But I don't think there are any problems in practical use.

For example, KV has a limitation of only being able to call the API up to 1000 operations per 1 worker invocation.

However, via this bridge, the API call becomes a separate worker invocation, which circumvents that limitation.

This may be a problem after you deployed that worker.

Since wrangler(miniflare) does not support Vectorize yet, you need --remote to interact with Vectorize binding.

cloudflare/workers-sdk#4360

-const putKV = async (API_KEY, API_URL, [key, value]) => {
-  const res = await fetch(`${API_URL}/values/${key}`, {
-    method: "PUT",
-    headers: { Authorization: `Bearer ${API_KEY}` },
-    body: value,
-  });
-
-  const json = await res.json();
-  if (!json.success)
-    throw new Error(json.errors.map(({ message }) => message).join("\n"));
-};
+import { KVNamespace$ } from "cfw-bindings-wrangler-bridge";
+import { unstable_dev } from "wrangler";
+
+const worker = await unstable_dev(/* ... */);
+
+const putKV = async (KV_BINDING_NAME, [key, value]) => {
+  const KV = new KVNamespace$(
+    KV_BINDING_NAME,
+    { bridgeWorkerOrigin: `http://${worker.address}:${worker.port}` }
+  );
+  await KV.put(key, value);
+};
+
+await worker.stop();

// server.hooks.js
import { KVNamespace$, D1Database$ } from "cfw-bindings-wrangler-bridge";
import { dev } from "$app/environment";

export const handle = async ({ event, resolve }) => {
  if (dev) {
    event.platform = {
      env: {
        SESSIONS: new KVNamespace$("SESSIONS"),
        TODOS: new D1Database$("TODOS"),
      },
    };
  }

  return resolve(event);
};

import { getBindings } from "cfw-bindings-wrangler-bridge";
import { unstable_dev } from "wrangler";
import { dev } from "$app/environment";
import type { Handle } from "@sveltejs/kit";
import type { UnstableDevWorker } from "wrangler";

let worker: UnstableDevWorker;
let env: App.Platform["env"];
export const handle: Handle = async ({ event, resolve }) => {
  if (dev) {
    if (!env) {
      worker = await unstable_dev(
        "./node_modules/cfw-bindings-wrangler-bridge/worker/index.js",
        { experimental: { disableExperimentalWarning: true } },
      );
      env = await getBindings({
        bridgeWorkerOrigin: `http://${worker.address}:${worker.port}`,
      });
    }

    event.platform = { env };
  }

  return resolve(event);
};

---
// your-page.astro
import { getRuntime } from "@astrojs/cloudflare/runtime";
import { KVNamespace$ } from "cfw-bindings-wrangler-bridge";

let runtime = getRuntime(Astro.request) ?? {};
if (import.meta.env.DEV) {
  runtime.env = {
    NEWS: new KVNamespace$("NEWS"),
  };
}
---

<!-- ... -->