cf-bindings-proxy

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

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.

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

• put
• get
• list
• getWithMetadata
• delete

D1

• prepare
  • bind
  • run
  • all
  • first
  • raw
• batch
• exec
• dump

R2

• put
  • writeHttpMetadata
• get
  • writeHttpMetadata
  • text
  • json
  • arrayBuffer
  • blob
  • body
  • bodyUsed
• head
  • writeHttpMetadata
• list
  • writeHttpMetadata
• delete
• createMultipartUpload
• resumeMultipartUpload

Changelog

0.2.2

Patch Changes

• 5289f47: Fix accessing an instance of a binding through a variable multiple times interfacing on the same instance - create a new proxy instance for each time the binding is accessed.

  The below code is a good example of this fix. Previously, each time an action was performed using the d1 variable, it was always interfacing with the same instance. This change fixes that, so that each time the d1 variable is accessed below, it is interfacing with an entirely new instance of the binding. This prevents different actions on a binding via a variable from breaking each other.

  const insertQuery = [
  	`INSERT INTO comments (author, body, post_slug) VALUES ('Markus', 'Hello there!', ?);`,
  	`INSERT INTO comments (author, body, post_slug) VALUES ('Kristian', 'Great post!', ?);`,
  ];
  
  const d1 = binding<D1Database>('D1');
  
  const statements = insertQuery.map((query) => d1.prepare(query).bind('hello-world'));
  await d1.batch(statements);