Cloudflare Kv Agent Skill

Cloudflare Workers KV

Status: Production Ready ✅ | Last Verified: 2025-12-27

What Is Workers KV?

Global key-value storage on Cloudflare edge:

• Eventually consistent
• Low latency worldwide
• 1GB+ values supported
• TTL expiration
• Metadata support

Quick Start (5 Minutes)

1. Create KV Namespace

bunx wrangler kv namespace create MY_NAMESPACE
bunx wrangler kv namespace create MY_NAMESPACE --preview

2. Configure Binding

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-11",
  "kv_namespaces": [
    {
      "binding": "MY_NAMESPACE",
      "id": "<PRODUCTION_ID>",
      "preview_id": "<PREVIEW_ID>"
    }
  ]
}

3. Basic Operations

export default {
  async fetch(request, env, ctx) {
    // Write
    await env.MY_NAMESPACE.put('key', 'value');

    // Read
    const value = await env.MY_NAMESPACE.get('key');

    // Delete
    await env.MY_NAMESPACE.delete('key');

    return new Response(value);
  }
};

Load references/setup-guide.md for complete setup.

KV API Methods

put() - Write

// Basic
await env.MY_NAMESPACE.put('key', 'value');

// With TTL (1 hour)
await env.MY_NAMESPACE.put('key', 'value', {
  expirationTtl: 3600
});

// With expiration timestamp
await env.MY_NAMESPACE.put('key', 'value', {
  expiration: Math.floor(Date.now() / 1000) + 3600
});

// With metadata
await env.MY_NAMESPACE.put('key', 'value', {
  metadata: { role: 'admin', created: Date.now() }
});

get() - Read

// Simple get
const value = await env.MY_NAMESPACE.get('key');

// With type
const text = await env.MY_NAMESPACE.get('key', 'text');
const json = await env.MY_NAMESPACE.get('key', 'json');
const buffer = await env.MY_NAMESPACE.get('key', 'arrayBuffer');
const stream = await env.MY_NAMESPACE.get('key', 'stream');

// With metadata
const { value, metadata } = await env.MY_NAMESPACE.getWithMetadata('key');

delete() - Remove

await env.MY_NAMESPACE.delete('key');

list() - List Keys

// Basic list
const { keys } = await env.MY_NAMESPACE.list();

// With prefix
const { keys } = await env.MY_NAMESPACE.list({
  prefix: 'user:',
  limit: 100
});

// Pagination
const { keys, cursor } = await env.MY_NAMESPACE.list({
  cursor: previousCursor
});

Critical Rules

Always Do ✅

• Use TTL for temporary data
• Handle null (key might not exist)
• Use metadata for small data
• Paginate lists (max 1000 keys)
• Use prefixes for organization
• Cache in Worker (avoid multiple KV calls)
• Use waitUntil() for async writes
• Handle eventual consistency
• Monitor rate limits

10. Use JSON.stringify for objects

Never Do ❌

• Never assume instant consistency
• Never exceed 25MB per value
• Never list all keys without pagination
• Never skip error handling
• Never use for real-time data
• Never exceed rate limits (1000 writes/second)
• Never store secrets unencrypted
• Never use as database (no transactions)
• Never ignore metadata limits (1024 bytes)

10. Never skip TTL for temporary data

Common Use Cases

Use Case 1: API Response Caching

const cacheKey = `api:${url}`;
let cached = await env.MY_NAMESPACE.get(cacheKey, 'json');

if (!cached) {
  cached = await fetch(url).then(r => r.json());
  await env.MY_NAMESPACE.put(cacheKey, JSON.stringify(cached), {
    expirationTtl: 300  // 5 minutes
  });
}

return Response.json(cached);

Use Case 2: User Preferences

const userId = '123';
const preferences = {
  theme: 'dark',
  language: 'en'
};

await env.MY_NAMESPACE.put(
  `user:${userId}:preferences`,
  JSON.stringify(preferences),
  {
    metadata: { updated: Date.now() }
  }
);

Use Case 3: Rate Limiting

const key = `ratelimit:${ip}`;
const count = parseInt(await env.MY_NAMESPACE.get(key) || '0');

if (count >= 100) {
  return new Response('Rate limit exceeded', { status: 429 });
}

await env.MY_NAMESPACE.put(key, String(count + 1), {
  expirationTtl: 60  // 1 minute window
});

Use Case 4: List with Prefix

const { keys } = await env.MY_NAMESPACE.list({
  prefix: 'user:',
  limit: 100
});

const users = await Promise.all(
  keys.map(({ name }) => env.MY_NAMESPACE.get(name, 'json'))
);

Use Case 5: waitUntil() Pattern

export default {
  async fetch(request, env, ctx) {
    // Don't wait for KV write
    ctx.waitUntil(
      env.MY_NAMESPACE.put('analytics', JSON.stringify(data))
    );

    return new Response('OK');
  }
};

Limits (Summary)

Key Limits:

• Key size: 512 bytes max
• Value size: 25 MB max
• Metadata: 1024 bytes max

Rate Limits:

• Writes: 1000/sec per key
• List: 100/sec per namespace
• Reads: Unlimited

For detailed limits, pricing, and optimization strategies, load references/limits-quotas.md

Eventual Consistency

KV is eventually consistent:

• Writes propagate globally (~60 seconds)
• Not suitable for real-time data
• Use D1 for strong consistency

Pattern:

// Write
await env.MY_NAMESPACE.put('key', 'value');

// May not be visible immediately in other regions
const value = await env.MY_NAMESPACE.get('key');  // Might be null

When to Load References

Load specific reference files based on task context:

For Setup & Configuration:

• Load references/setup-guide.md when creating namespaces or configuring bindings

For Performance Optimization:

• Load references/best-practices.md when implementing caching or optimizing performance
• Load references/performance-tuning.md for advanced optimization scenarios, cacheTtl strategies, or benchmarking

For API Usage:

• Load references/workers-api.md when implementing KV operations or need method signatures

For Troubleshooting:

• Load references/troubleshooting.md when debugging errors or consistency issues

For Limits & Quotas:

• Load references/limits-quotas.md when planning capacity or encountering quota errors

For Migration:

• Load references/migration-guide.md when migrating from localStorage, Redis, D1, R2, or other storage solutions

Resources

References (references/):

• best-practices.md - Production patterns, caching strategies, rate limit handling, error recovery
• setup-guide.md - Complete setup with Wrangler CLI commands, namespace creation, bindings configuration
• workers-api.md - Complete API reference, consistency model (eventual consistency), limits & quotas, performance optimization
• troubleshooting.md - Comprehensive error catalog with solutions
• limits-quotas.md - Detailed limits, quotas, pricing, and optimization tips
• migration-guide.md - Complete migration guides from localStorage, Redis, D1, R2, and other storage solutions
• performance-tuning.md - Advanced cacheTtl strategies, bulk operations, key design, benchmarking techniques

Templates (templates/):

• kv-basic-operations.ts - Basic KV operations (get, put, delete, list)
• kv-caching-pattern.ts - HTTP caching with KV
• kv-list-pagination.ts - List with cursor pagination
• kv-metadata-pattern.ts - Metadata usage patterns
• wrangler-kv-config.jsonc - KV namespace bindings

Scripts (scripts/):

• check-versions.sh - Validate KV API endpoints and package versions
• test-kv-connection.sh - Test KV namespace connection and operations
• setup-kv-namespace.sh - Interactive namespace setup wizard
• validate-kv-config.sh - Validate wrangler.jsonc configuration
• analyze-kv-usage.sh - Analyze code for KV usage patterns and optimizations

Commands:

• /cloudflare-kv:setup - Interactive KV namespace setup wizard
• /cloudflare-kv:test - Test KV operations and connection
• /cloudflare-kv:optimize - Analyze and optimize KV usage

Agents:

• kv-optimizer - Analyzes KV usage and suggests performance optimizations
• kv-debugger - Helps debug KV errors and consistency issues

Examples (examples/):

• rate-limiting/ - Complete rate limiting implementation (fixed window, sliding window, token bucket, multi-tier)
• session-management/ - Production session store with TTL expiration, metadata tracking, and admin controls
• api-caching/ - HTTP response caching patterns (cache-aside, stale-while-revalidate, conditional caching, ETag)
• config-management/ - Feature flags, A/B testing, environment configs, version tracking, hot-reload

Official Documentation

• KV Overview: https://developers.cloudflare.com/kv/
• KV API: https://developers.cloudflare.com/kv/api/
• Best Practices: https://developers.cloudflare.com/kv/best-practices/

Questions? Issues?

• Check references/setup-guide.md for complete setup
• Verify namespace binding configured
• Handle eventual consistency
• Check rate limits