| name | cloudflare-kv |
| description | Cloudflare Workers KV global key-value storage. Use for namespaces, caching, TTL, or encountering KV_ERROR, 429 rate limits, consistency issues. |
| license | MIT |
| metadata | {"version":"3.0.0","last_verified":"2025-12-27","production_tested":true,"token_savings":"~60%","errors_prevented":5,"templates_included":5,"references_included":7,"keywords":["kv storage","cloudflare kv","workers kv","kv namespace","kv bindings","kv cache","kv ttl","kv metadata","kv list","kv pagination","cache optimization","edge caching","KV_ERROR","429 too many requests","kv rate limit","eventually consistent","wrangler kv","kv operations","key value storage"]} |
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) {
await env.MY_NAMESPACE.put('key', 'value');
const value = await env.MY_NAMESPACE.get('key');
await env.MY_NAMESPACE.delete('key');
return new Response(value);
}
};
Load references/setup-guide.md for complete setup.
KV API Methods
put() - Write
await env.MY_NAMESPACE.put('key', 'value');
await env.MY_NAMESPACE.put('key', 'value', {
expirationTtl: 3600
});
await env.MY_NAMESPACE.put('key', 'value', {
expiration: Math.floor(Date.now() / 1000) + 3600
});
await env.MY_NAMESPACE.put('key', 'value', {
metadata: { role: 'admin', created: Date.now() }
});
get() - Read
const value = await env.MY_NAMESPACE.get('key');
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');
const { value, metadata } = await env.MY_NAMESPACE.getWithMetadata('key');
delete() - Remove
await env.MY_NAMESPACE.delete('key');
list() - List Keys
const { keys } = await env.MY_NAMESPACE.list();
const { keys } = await env.MY_NAMESPACE.list({
prefix: 'user:',
limit: 100
});
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
- 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)
- 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
});
}
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
});
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) {
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:
await env.MY_NAMESPACE.put('key', 'value');
const value = await env.MY_NAMESPACE.get('key');
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
Questions? Issues?
- Check
references/setup-guide.md for complete setup
- Verify namespace binding configured
- Handle eventual consistency
- Check rate limits