KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #codex #ai-agents #claude-code #dsh #dsh-plugin #cli #macos #ai-agent #deepseek-harness #open-source

cf-bindings-proxy

★ 99 Open GitHub ↗

Experimental proxy for interfacing with bindings in projects targeting Cloudflare Pages

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
  <h3 align="center">cf-bindings-proxy</h3>

<p align="center">
    Experimental proxy for interfacing with bindings
    <br />
    in projects targeting Cloudflare Pages.
  </p>
</p>

---

---

This library was written to accompany [`@cloudflare/next-on-pages`](https://github.com/cloudflare/next-on-pages), so that you can use bindings when developing Next.js apps locally through `next dev`.

It is intended to be used for frameworks that do not support Cloudflare bindings in a fast HMR environment.

## Usage

Add the library to your project.

```sh
npm add cf-bindings-proxy
```

In a separate terminal window, run the following command to start the proxy, passing through your bindings are arguments.

```sh
npx cf-bindings-proxy --kv=MY_KV
```

In your project's code, import the `binding` function from `cf-bindings-proxy` and use it to interact with your bindings.

```ts
import { binding } from 'cf-bindings-proxy';

const value = await binding<KVNamespace>('MY_KV').get('key');
```

It is also possible to specify a custom fallback for use in production instead of `process.env`.

```ts
import { binding } from 'cf-bindings-proxy';

const value = await binding<KVNamespace>('MY_KV', { fallback: platform.env }).get('key');
```

## How It Works

Starting the proxy spawns an instance of Wrangler using a template, passing through any commands and bindings that are supplied to the CLI. It uses port `8799`.

In development mode, when interacting with a binding through the `binding('BINDING_NAME')` function, it sends HTTP requests to the proxy. These HTTP requests contain destructured function calls, which are then reconstructed and executed inside the proxy. The result is then returned to the client.

When building for production, `binding('BINDING_NAME')` simply calls `process.env.BINDING_NAME` to retrieve the binding instead. If you wish to use a custom fallback like `platform.env` instead of `process.env`, you can pass a custom fallback to the binding call with `binding('BINDING_NAME', { fallback: platform.env })`.

### When It's Active

Calls to `binding('BINDING_NAME')` will try to use the proxy when either of the following two conditions are met:

- The `ENABLE_BINDINGS_PROXY` environment variable is set to `true`.
  OR
- The `DISABLE_BINDINGS_PROXY` environment variable is not set and `NODE_ENV` is set to `development`.

## Supported

Note: Functionality and bindings not listed below may still work but have not been tested.

#### KV

- [x] put
- [x] get
- [x] list
- [x] getWithMetadata
- [x] delete

#### D1

- [x] prepare
  - [x] bind
  - [x] run
  - [x] all
  - [x] first
  - [x] raw
- [x] batch
- [x] exec
- [x] dump

#### R2

- [x] put
  - [x] writeHttpMetadata
  - [x] _value type_: ArrayBuffer
  - [x] _value type_: string
  - [x] _value type_: Blob
  - [x] _value type_: ReadableStream
- [x] get
  - [x] writeHttpMetadata
  - [x] text
  - [x] json
  - [x] arrayBuffer
  - [x] blob
  - [x] body
  - [x] bodyUsed
- [x] head
  - [x] writeHttpMetadata
- [x] list
  - [x] writeHttpMetadata
- [x] delete
- [ ] createMultipartUpload (needs more tests)
- [ ] resumeMultipartUpload (needs more tests)

#### Cache API

- [x] put
- [x] match
- [x] delete

cf-bindings-proxy

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README