cfw-bindings-wrangler-bridge

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.

Important

If your purpose is to mock bindings only for closed, local development and no initial data is needed(or can be easily prepared), you may not need this bridge.

For these cases, we recommend using mock APIs like:

• miniflare@3 API
  • Some of frameworks may have its own support for miniflare in their adapters like SolidStart
• getPlatformProxy() from wrangler module

If those do not match for your case or you really need the remote data, please go ahead. 🤤

How it works

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 & Prerequisite

Install bridge as usual.

npm install -D cfw-bindings-wrangler-bridge

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

Usage

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.

🅰️ With external wrangler dev process

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.

🅱️ With unstable_dev() API by wrangler package

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.

Advanced usage

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");

Note

AFAIK, this is the only way to achieve this situation for now.

Supported bindings

binding	module	support	memo
KV namespace	KVNamespace$	💯
R2 bucket	R2Bucket$	💯
D1 database	D1Database$	💯
Service	Fetcher$	💯
Queue	WorkerQueue$	💯	Producer usage only
Vectorize	VectorizeIndex$	💯	--remote only for now

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

Known limitations

Compatibility issues

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.

Max limits for API call

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.

Vectorize bindings

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

cloudflare/workers-sdk#4360

Examples

CLI

If you are using REST API in your CLI, now you can replace it.

-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();

SvelteKit local development

Be sure to wrap with if (dev) {}, not to be included in production build.

// 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);
};

OR

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);
};

Astro local development

Be sure to wrap with if (import.meta.env.DEV) {}, not to be included in production build.

---
// 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"),
  };
}
---

<!-- ... -->