cf-bindings-proxy

Experimental proxy for interfacing with bindings
in projects targeting Cloudflare Pages.

This library was written to accompany @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.

npm add cf-bindings-proxy

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

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.

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.

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