Skip to content

Conversation

@connorads
Copy link

@connorads connorads commented Nov 23, 2025

What?

Add a Cloudflare KV adapter to extend recent KV support (#9913)
Discussion: #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 connorads marked this pull request as ready for review November 30, 2025 14:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant