tomevault-io 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 URLKV_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!
Converted and distributed by TomeVault — claim your Tome and manage your conversions.