vercel-kv

# Vercel KV (Redis-Compatible Storage)

**Status**: Production Ready
**Last Updated**: 2025-12-14
**Dependencies**: None
**Latest Versions**: `@vercel/kv@3.0.0`

---

## Quick Start (3 Minutes)

### 1. Create & Configure

```bash
# Create KV database in Vercel dashboard: Storage → Create Database → KV
vercel env pull .env.local
```

Creates environment variables:
- `KV_REST_API_URL` - Your KV database URL
- `KV_REST_API_TOKEN` - Auth token

### 2. Install

```bash
bun add @vercel/kv
```

### 3. Use in Your App

**Next.js Server Action:**
```typescript
'use server';

import { kv } from '@vercel/kv';

export async function incrementViews(slug: string) {
  const views = await kv.incr(`views:${slug}`);
  return views;
}
```

**Edge API Route:**
```typescript
import { kv } from '@vercel/kv';

export const runtime = 'edge';

export async function GET(request: Request) {
  const value = await kv.get('mykey');
  return Response.json({ value });
}
```

---

## Critical Rules

### Always Do

| Rule | Why |
|------|-----|
| Set TTL for temporary data | `setex('key', 3600, value)` - Avoid memory leaks |
| Use namespaced keys | `user:123:profile` not `123` - Prevents collisions |
| Handle null returns | Non-existent keys return `null` |
| Use pipeline for batch ops | Single round-trip reduces latency |
| Serialize JSON-compatible only | No functions, circular references |
| Monitor command usage | Stay within free tier (30K/month) |

### Never Do

| Rule | Why |
|------|-----|
| Store sensitive data unencrypted | KV not encrypted at rest by default |
| Forget to set TTL | Keys without TTL stay forever |
| Use generic key names | `data`, `cache` will collide |
| Store large values (>1MB) | Use Vercel Blob instead |
| Use as primary database | KV is for cache, not persistence |
| Commit `.env.local` | Contains KV tokens |

---

## Core Operations

**Set/Get with TTL:**
```typescript
import { kv } from '@vercel/kv';

// Set with TTL (expires in 1 hour)
await kv.setex('session:abc',