payload icon indicating copy to clipboard operation
payload copied to clipboard

feat: add cloudflare kv adapter

Open connorads opened this issue 4 months ago • 0 comments

What?

Add a Cloudflare KV adapter to extend recent KV support (https://github.com/payloadcms/payload/pull/9913) Discussion: https://github.com/payloadcms/payload/discussions/14431

👋 I'm very open to comments and feedback

Why?

So that Cloudflare users can use Cloudflare KV as a backing store for Payload’s KV API.

How?

  • Implement a @payloadcms/kv-cloudflare package that satisfies the KVAdapter interface
  • Prefix keys to avoid collisions within a shared KV namespace
  • Use Cloudflare KV’s pagination API to implement keys() and clear()
  • Wire the package into the monorepo build and test setup

Testing

Automated tests

  • Extended the existing KV adapter integration suite in test/kv/int.spec.ts to run against cloudflareKVAdapter alongside the in-memory and Redis adapters, exercising:
    • set, get, has, keys, delete and clear
    • serialisation/deserialisation of values via Cloudflare KV
  • Spin up a Miniflare instance in beforeAll with a PAYLOAD_KV namespace and pass its binding into the adapter to mirror how Workers/Pages bindings are provided in production.
  • Added a dedicated Cloudflare KV Pagination test when:
    • there are fewer than 1000, exactly 1000, and more than 1000 keys (1000 is the limit)
    • list_complete is true and cursor is omitted by Cloudflare
    • multiple key prefixes share the same KV namespace (ensuring the adapter only returns / clears its own keys)

Manual integration test

  1. Created this repo: https://github.com/connorads/payload-cloudflare-kv-test
  2. Published the plugin to npm: https://www.npmjs.com/package/@connorads/kv-cloudflare
  3. Installed it into a sample Payload app and configured it to use a Cloudflare KV binding
  4. Verified basic CRUD behaviour via the simple TODO app
    image image

connorads avatar Nov 23 '25 14:11 connorads