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

# 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

bun add @vercel/kv

3. Use in Your App

Next.js Server Action:

'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:

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:

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

// Set with TTL (expires in 1 hour)
await kv.setex('session:abc', 3600, { userId: 123 });

// Get value
const session = await kv.get('session:abc');

// Delete
await kv.del('session:abc');

Atomic Operations:

const views = await kv.incr('views:post:123');
const wasSet = await kv.setnx('lock:process', 'running'); // Set if not exists

Multiple Keys:

const values = await kv.mget('user:1', 'user:2', 'user:3');
await kv.mset({ 'user:1': data1, 'user:2': data2 });

Known Issues Prevention

This skill prevents 10 documented issues:

| # | Error | Quick Fix | |---|-------|-----------| | 1 | KV_REST_API_URL not defined | Run vercel env pull .env.local | | 2 | Cannot serialize BigInt | Convert to string, use plain objects | | 3 | Unexpected data returned | Use namespaced keys: user:123:profile | | 4 | Memory grows indefinitely | Use setex() with TTL | | 5 | Rate limit exceeded | Batch operations, upgrade plan | | 6 | Value too large | Use Vercel Blob for >100KB | | 7 | TypeScript type errors | Use kv.get<Type>() with Zod validation | | 8 | Pipeline silent failures | Check results array from exec() | | 9 | Scan timeout errors | Limit count, iterate with cursor | | 10 | Session expires too early | Use expire() for sliding window |

See: references/known-issues.md for complete solutions with code examples.

Common Patterns Summary

| Pattern | Use Case | Key API | |---------|----------|---------| | Cache-Aside | Read caching | get → fetch → setex | | Write-Through | Write consistency | setex on write, del on delete | | Rate Limiting | API protection | incr + expire | | Session Management | User sessions | setex, get, expire, del | | Distributed Lock | Concurrency control | setnx + expire + del | | Leaderboard | Rankings | zadd, zrange, zrevrank | | Pipeline | Batch operations | pipeline().exec() |

See: references/common-patterns.md for complete implementations.

Configuration

.env.local

# Created by: vercel env pull .env.local
KV_REST_API_URL="https://your-database.kv.vercel-storage.com"
KV_REST_API_TOKEN="your-token-here"

.gitignore

.env.local
.env*.local

When to Load References

| Reference | Load When... | |-----------|--------------| | references/known-issues.md | Debugging KV errors, type issues, or performance problems | | references/common-patterns.md | Implementing caching, sessions, rate limiting, leaderboards, or locks |

Dependencies

{
  "dependencies": {
    "@vercel/kv": "^3.0.0"
  }
}

Free Tier Limits: 30,000 commands/month, 256MB storage

Official Documentation

• Vercel KV: https://vercel.com/docs/storage/vercel-kv
• SDK Reference: https://vercel.com/docs/storage/vercel-kv/kv-reference
• GitHub: https://github.com/vercel/storage
• Redis Commands: https://redis.io/commands

Troubleshooting

| Problem | Solution | |---------|----------| | KV_REST_API_URL not defined | Run vercel env pull .env.local | | Rate limit exceeded | Use mget/pipeline, upgrade plan | | Values not expiring | Use setex() not set() | | JSON serialization error | Use plain objects, convert BigInt to string |

Token Savings: ~60% (patterns extracted to references) Error Prevention: 100% (all 10 documented issues) Ready for production!