Cloudflare Kv

Cloudflare Workers KV

Complete knowledge domain for Cloudflare Workers KV - global, low-latency key-value storage on Cloudflare's edge network.

---

Auto-Trigger Keywords

Primary Keywords

• kv storage
• cloudflare kv
• kv namespace
• workers kv
• kv bindings
• kv cache
• kv api
• key value storage
• edge storage

Secondary Keywords

• kv get
• kv put
• kv delete
• kv list
• kv ttl
• kv expiration
• kv metadata
• cache ttl
• kv pagination
• kv prefix
• kv wrangler
• namespace create
• kv operations
• eventually consistent

Error-Based Keywords

• KV_ERROR
• 429 too many requests
• kv rate limit
• kv quota exceeded
• kv write limit
• concurrent writes kv
• kv_put_failed
• metadata too large
• value too large
• key too long
• cacheTtl minimum

Framework Integration Keywords

• kv hono
• kv workers api
• kv cloudflare workers
• wrangler kv
• kv bindings workers

---

What This Skill Does

This skill provides complete Workers KV knowledge including:

• ✅ KV Namespace Management - Create, configure, and bind namespaces
• ✅ CRUD Operations - get(), put(), delete(), list()
• ✅ Bulk Operations - Bulk reads and REST API batch writes
• ✅ Metadata Storage - Store up to 1KB metadata per key
• ✅ TTL & Expiration - Automatic key expiration with TTL or absolute time
• ✅ CacheTtl Optimization - Control edge caching for faster reads
• ✅ List Operations - Pagination with cursor, prefix filtering
• ✅ Performance Patterns - Key coalescing, caching strategies
• ✅ Error Handling - Rate limit retries, eventual consistency handling
• ✅ Development vs Production - Environment-specific namespaces

---

Known Issues Prevented

Issue	Description	Prevention
1 write/sec limit	Concurrent writes to same key cause 429 errors	Document rate limits + retry logic with backoff
Eventually consistent	Writes take up to 60s to propagate globally	Set expectations, use cacheTtl appropriately
cacheTtl minimum 60s	Setting lower than 60s fails	Always use 60+ seconds for cacheTtl
Metadata 1024 byte limit	Exceeding metadata size causes errors	Validate metadata size before put()
Value 25MB limit	Large values fail to store	Check size before writing
1000 operations/invocation	Exceeding causes Worker failure	Use bulk operations, batch reads

---

When to Use This Skill

✅ Use this skill when:

• Storing configuration data or feature flags
• Caching API responses or computed values
• Storing user preferences or session data
• Building read-heavy applications
• Implementing A/B testing configurations
• Storing authentication tokens or JWT data
• Building CDN-like caching layers
• Storing routing tables or redirect maps
• Managing global application state

❌ When NOT to use:

• You need strong consistency (use Durable Objects)
• You need atomic operations (use Durable Objects)
• You need relational data (use cloudflare-d1)
• You need frequent writes to same key (>1/sec)
• You need large file storage (use cloudflare-r2)
• You need vector search (use cloudflare-vectorize)

---

Quick Example

import { Hono } from 'hono';

type Bindings = {
  CONFIG: KVNamespace;
};

const app = new Hono<{ Bindings: Bindings }>();

// Write with expiration
app.post('/config/:key', async (c) => {
  const key = c.req.param('key');
  const value = await c.req.text();

  await c.env.CONFIG.put(key, value, {
    expirationTtl: 3600, // Expire in 1 hour
    metadata: { updatedAt: Date.now(), updatedBy: 'admin' },
  });

  return c.json({ success: true, key });
});

// Read with cache optimization
app.get('/config/:key', async (c) => {
  const key = c.req.param('key');

  const { value, metadata } = await c.env.CONFIG.getWithMetadata(key, {
    type: 'json',
    cacheTtl: 300, // Cache for 5 minutes at edge
  });

  if (!value) {
    return c.json({ error: 'Not found' }, 404);
  }

  return c.json({ value, metadata });
});

// List with prefix and pagination
app.get('/config/list/:prefix?', async (c) => {
  const prefix = c.req.param('prefix') || '';
  const cursor = c.req.query('cursor');

  const result = await c.env.CONFIG.list({
    prefix,
    limit: 100,
    cursor: cursor || undefined,
  });

  return c.json({
    keys: result.keys,
    hasMore: !result.list_complete,
    cursor: result.cursor,
  });
});

export default app;

---

Files Included

Core Documentation

• SKILL.md - Complete KV knowledge domain with progressive disclosure
• README.md - This file - overview and auto-trigger keywords

References (Extended Documentation)

• references/best-practices.md - Production patterns, caching strategies, error recovery
• references/setup-guide.md - Complete setup with Wrangler CLI commands
• references/workers-api.md - Complete API reference and consistency model
• references/troubleshooting.md - Comprehensive error catalog with solutions
• references/limits-quotas.md - Detailed limits, quotas, pricing, optimization
• references/migration-guide.md - Migration guides from localStorage, Redis, D1, R2, and other solutions
• references/performance-tuning.md - Advanced cacheTtl strategies, bulk operations, benchmarking

Templates (Code Examples)

• templates/wrangler-kv-config.jsonc - KV namespace bindings
• templates/kv-basic-operations.ts - CRUD operations Worker
• templates/kv-caching-pattern.ts - Cache optimization patterns
• templates/kv-list-pagination.ts - List with cursor pagination
• templates/kv-metadata-pattern.ts - Metadata usage patterns

Scripts (Automation Tools)

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

Commands (Slash Commands)

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

Agents (Autonomous Assistants)

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

Examples (Working Code)

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

---

Dependencies

• cloudflare-worker-base - For Hono + Vite + Worker setup
• wrangler - For KV namespace management

---

Production Status

✅ Production Ready

This skill is based on:

• Official Cloudflare KV documentation
• Cloudflare Workers SDK examples
• Production-tested patterns
• Latest package versions (verified 2025-12-27)

---

Related Skills

• cloudflare-worker-base - Base Worker setup with Hono
• cloudflare-d1 - Serverless SQLite database
• cloudflare-r2 - Object storage
• cloudflare-workers-ai - AI inference on Workers

---

Last Updated: 2025-12-27 Status: Production Ready ✅ Maintainer: Claude Skills Maintainers | maintainers@example.com