Skip to content
ACMS ACMS Docs

Cloudflare KV Adapter

The Cloudflare KV adapter stores your content schema in Cloudflare Workers KV, providing globally distributed key-value storage with edge reads.

Installation

Section titled “Installation”
Terminal window
npm install @useacms/cli

Configuration

Section titled “Configuration”
import { defineConfig } from '@useacms/client';
import { localFile, cloudflareKV } from '@useacms/cli/adapters';


export default defineConfig({
  dev: localFile({ path: './acms.json' }),
  production: cloudflareKV({
    accountId: process.env.CF_ACCOUNT_ID,
    namespaceId: process.env.CF_KV_NAMESPACE_ID,
    apiToken: process.env.CF_API_TOKEN,
  }),
});

Options

Section titled “Options”
OptionTypeRequiredDescription
accountIdstringYesCloudflare account ID
namespaceIdstringYesKV namespace ID
apiTokenstringYesCloudflare API token with KV read/write permissions

Setup

Section titled “Setup”

1. Create a Cloudflare API Token

Section titled “1. Create a Cloudflare API Token”
  1. Go to Cloudflare Dashboard > Profile > API Tokens.
  2. Create a new token with “Workers KV Storage” read and write permissions.
  3. Copy the token.

2. Create a KV Namespace

Section titled “2. Create a KV Namespace”

Using the Cloudflare dashboard:

  1. Go to Workers & Pages > KV.
  2. Create a new namespace (e.g., acms-content).
  3. Copy the namespace ID.

Or using Wrangler:

Terminal window
npx wrangler kv namespace create "acms-content"

3. Configure Environment Variables

Section titled “3. Configure Environment Variables”
.env
CF_ACCOUNT_ID=your_account_id
CF_KV_NAMESPACE_ID=your_namespace_id
CF_API_TOKEN=your_api_token

Usage

Section titled “Usage”
Terminal window
acms push    # Upload to Cloudflare KV
acms pull    # Download from Cloudflare KV
acms sync    # Bi-directional sync

How It Works

Section titled “How It Works”
  • Read: Fetches the schema from the KV namespace using the Cloudflare API.
  • Write: Writes the schema as a JSON value to the KV namespace.

KV provides eventual consistency for writes (usually propagates globally within 60 seconds) and strong consistency for reads from the same location.

Use Cases

Section titled “Use Cases”
  • Cloudflare-hosted apps — Native integration with Cloudflare Workers and Pages.
  • Global distribution — Content available at hundreds of edge locations.
  • Runtime strategy — Works well with strategy: 'runtime' for dynamic content.
  • Cloudflare Pages — Ideal for sites deployed on Cloudflare Pages.

Limitations

Section titled “Limitations”
  • Write propagation is eventually consistent (up to 60 seconds globally).
  • KV has a value size limit of 25 MB per key.
  • Requires a Cloudflare account.

Next Steps

Section titled “Next Steps”