OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add secondsky/claude-skills --skill cloudflare-kv
Cloudflare Workers KV global key-value storage. Use for namespaces, caching, TTL, or encountering KV_ERROR, 429 rate limits, consistency issues.
npx skills add secondsky/claude-skills --skill cloudflare-kv
Status: Production Ready ✅ | Last Verified: 2025-12-27
Global key-value storage on Cloudflare edge:
Load references/setup-guide.md for complete setup.
Key Limits:
Rate Limits:
For detailed limits, pricing, and optimization strategies, load references/limits-quotas.md
KV is eventually consistent:
Pattern:
Load specific reference files based on task context:
For Setup & Configuration:
references/setup-guide.md when creating namespaces or configuring bindingsFor Performance Optimization:
references/best-practices.md when implementing caching or optimizing performancereferences/performance-tuning.md for advanced optimization scenarios, cacheTtl strategies, or benchmarkingFor API Usage:
references/workers-api.md when implementing KV operations or need method signaturesFor Troubleshooting:
references/troubleshooting.md when debugging errors or consistency issuesFor Limits & Quotas:
references/limits-quotas.md when planning capacity or encountering quota errorsFor Migration:
references/migration-guide.md when migrating from localStorage, Redis, D1, R2, or other storage solutionsReferences (references/):
best-practices.md - Production patterns, caching strategies, rate limit handling, error recoverysetup-guide.md - Complete setup with Wrangler CLI commands, namespace creation, bindings configurationworkers-api.md - Complete API reference, consistency model (eventual consistency), limits & quotas, performance optimizationtroubleshooting.md - Comprehensive error catalog with solutionslimits-quotas.md - Detailed limits, quotas, pricing, and optimization tipsmigration-guide.md - Complete migration guides from localStorage, Redis, D1, R2, and other storage solutionsperformance-tuning.md - Advanced cacheTtl strategies, bulk operations, key design, benchmarking techniquesTemplates (templates/):
kv-basic-operations.ts - Basic KV operations (get, put, delete, list)kv-caching-pattern.ts - HTTP caching with KVkv-list-pagination.ts - List with cursor paginationkv-metadata-pattern.ts - Metadata usage patternswrangler-kv-config.jsonc - KV namespace bindingsScripts (scripts/):
check-versions.sh - Validate KV API endpoints and package versionstest-kv-connection.sh - Test KV namespace connection and operationssetup-kv-namespace.sh - Interactive namespace setup wizardvalidate-kv-config.sh - Validate wrangler.jsonc configurationanalyze-kv-usage.sh - Analyze code for KV usage patterns and optimizationsCommands:
/cloudflare-kv:setup - Interactive KV namespace setup wizard/cloudflare-kv:test - Test KV operations and connection/cloudflare-kv:optimize - Analyze and optimize KV usageAgents:
kv-optimizer - Analyzes KV usage and suggests performance optimizationskv-debugger - Helps debug KV errors and consistency issuesExamples (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 controlsapi-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-reloadQuestions? Issues?
references/setup-guide.md for complete setup{
"name": "my-worker",
"main": "src/index.ts",
"compatibility_date": "2025-10-11",
"kv_namespaces": [
{
"binding": "MY_NAMESPACE",
"id": "<PRODUCTION_ID>",
"preview_id": "<PREVIEW_ID>"
}
]
}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);
}
};// 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() }
});// 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');await env.MY_NAMESPACE.delete('key');// 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
});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);const userId = '123';
const preferences = {
theme: 'dark',
language: 'en'
};
await env.MY_NAMESPACE.put(
`user:${userId}:preferences`,
JSON.stringify(preferences),
{
metadata: { updated: Date.now() }
}
);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
});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'))
);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');
}
};// 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