1# KV Configuration
2 
3## Create Namespace
4 
5```bash
6wrangler kv namespace create MY_NAMESPACE
7# Output: { binding = "MY_NAMESPACE", id = "abc123..." }
8 
9wrangler kv namespace create MY_NAMESPACE --preview  # For local dev
10```
11 
12## Workers Binding
13 
14**wrangler.jsonc:**
15```jsonc
16{
17  "kv_namespaces": [
18    {
19      "binding": "MY_KV",
20      "id": "abc123xyz789"
21    },
22    // Optional: Different namespace for preview/development
23    {
24      "binding": "MY_KV",
25      "preview_id": "preview-abc123"
26    }
27  ]
28}
29```
30 
31## TypeScript Types
32 
33**env.d.ts:**
34```typescript
35interface Env {
36  MY_KV: KVNamespace;
37  SESSIONS: KVNamespace;
38  CACHE: KVNamespace;
39}
40```
41 
42**worker.ts:**
43```typescript
44export default {
45  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
46    // env.MY_KV is now typed as KVNamespace
47    const value = await env.MY_KV.get("key");
48    return new Response(value || "Not found");
49  }
50} satisfies ExportedHandler<Env>;
51```
52 
53**Type-safe JSON operations:**
54```typescript
55interface UserProfile {
56  name: string;
57  email: string;
58  role: "admin" | "user";
59}
60 
61const profile = await env.USERS.get<UserProfile>("user:123", "json");
62// profile: UserProfile | null (type-safe!)
63if (profile) {
64  console.log(profile.name); // TypeScript knows this is a string
65}
66```
67 
68## CLI Operations
69 
70```bash
71# Put
72wrangler kv key put --binding=MY_KV "key" "value"
73wrangler kv key put --binding=MY_KV "key" --path=./file.json --ttl=3600
74 
75# Get
76wrangler kv key get --binding=MY_KV "key"
77 
78# Delete
79wrangler kv key delete --binding=MY_KV "key"
80 
81# List
82wrangler kv key list --binding=MY_KV --prefix="user:"
83 
84# Bulk operations (max 10,000 keys per file)
85wrangler kv bulk put data.json --binding=MY_KV
86wrangler kv bulk get keys.json --binding=MY_KV
87wrangler kv bulk delete keys.json --binding=MY_KV --force
88```
89 
90## Local Development
91 
92```bash
93wrangler dev                # Local KV (isolated)
94wrangler dev --remote       # Remote KV (production)
95 
96# Or in wrangler.jsonc:
97# "kv_namespaces": [{ "binding": "MY_KV", "id": "...", "remote": true }]
98```
99 
100## REST API
101 
102### Single Operations
103 
104```typescript
105import Cloudflare from 'cloudflare';
106 
107const client = new Cloudflare({
108  apiEmail: process.env.CLOUDFLARE_EMAIL,
109  apiKey: process.env.CLOUDFLARE_API_KEY
110});
111 
112// Single key operations
113await client.kv.namespaces.values.update(namespaceId, 'key', {
114  account_id: accountId,
115  value: 'value',
116  expiration_ttl: 3600
117});
118```
119 
120### Bulk Operations
121 
122```typescript
123// Bulk update (up to 10,000 keys, max 100MB total)
124await client.kv.namespaces.bulkUpdate(namespaceId, {
125  account_id: accountId,
126  body: [
127    { key: "key1", value: "value1", expiration_ttl: 3600 },
128    { key: "key2", value: "value2", metadata: { version: 1 } },
129    { key: "key3", value: "value3" }
130  ]
131});
132 
133// Bulk get (up to 100 keys)
134const results = await client.kv.namespaces.bulkGet(namespaceId, {
135  account_id: accountId,
136  keys: ["key1", "key2", "key3"]
137});
138 
139// Bulk delete (up to 10,000 keys)
140await client.kv.namespaces.bulkDelete(namespaceId, {
141  account_id: accountId,
142  keys: ["key1", "key2", "key3"]
143});
144```
145