vercel-kv

Vercel KV (Redis-Compatible Storage)

Status: Production Ready Last Updated: 2025-10-29 Dependencies: None Latest Versions: @vercel/kv@3.0.0

Quick Start (3 Minutes)

1. Create Vercel KV Database

# In your Vercel project dashboard
# Storage → Create Database → KV

# Pull environment variables locally
vercel env pull .env.local

This automatically creates:

• KV_REST_API_URL - Your KV database URL
• KV_REST_API_TOKEN - Auth token
• KV_REST_API_READ_ONLY_TOKEN - Read-only token (optional)

2. Install Package

npm install @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:

• Always set TTL for temporary data: await kv.setex('key', 3600, value)
• Use namespacing for keys: user:${id}:profile instead of just ${id}
• JSON values must be serializable (no functions, circular refs)

The 5-Step Setup Process

Step 1: Create KV Database

Option A: Vercel Dashboard

1. Go to your Vercel project
2. Storage → Create Database → KV
3. Name your database
4. Copy the environment variables

Option B: Vercel CLI

vercel env pull .env.local

This creates:

# .env.local (automatically created)
KV_REST_API_URL="https://xyz.kv.vercel-storage.com"
KV_REST_API_TOKEN="your-token-here"
KV_REST_API_READ_ONLY_TOKEN="your-readonly-token"

Key Points:

• One KV database per project recommended
• Free tier: 30,000 commands/month, 256MB storage
• Environment variables are automatically set for Vercel deployments

Step 2: Install and Configure

npm install @vercel/kv

For local development, create .env.local:

# .env.local
KV_REST_API_URL="https://your-db.kv.vercel-storage.com"
KV_REST_API_TOKEN="your-token"

For production, environment variables are automatically available.

Cloudflare Workers (using Vercel KV):

# wrangler.toml
[vars]
KV_REST_API_URL = "https://your-db.kv.vercel-storage.com"

[[secrets]]
KV_REST_API_TOKEN = "your-token"

Step 3: Basic Operations

Set/Get:

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

// Set a value
await kv.set('user:123', { name: 'Alice', email: 'alice@example.com' });

// Get a value
const user = await kv.get('user:123');
// Returns: { name: 'Alice', email: 'alice@example.com' }

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

// Check if key exists
const exists = await kv.exists('user:123'); // Returns 1 if exists, 0 if not

// Delete a key
await kv.del('user:123');

Atomic Operations:

// Increment counter
const views = await kv.incr('views:post:123');

// Decrement counter
const stock = await kv.decr('inventory:item:456');

// Increment by amount
await kv.incrby('score:user:789', 10);

// Set if not exists (returns 1 if set, 0 if key already exists)
const wasSet = await kv.setnx('lock:process', 'running');

Multiple Operations:

// Get multiple keys
const values = await kv.mget('user:1', 'user:2', 'user:3');
// Returns: [{ name: '...' }, { name: '...' }, null]

// Set multiple keys
await kv.mset({
  'user:1': { name: 'Alice' },
  'user:2': { name: 'Bob' }
});

// Delete multiple keys
await kv.del('key1', 'key2', 'key3');

Key Points:

• Values are automatically JSON-serialized
• null is returned for non-existent keys
• All operations are atomic
• TTL is in seconds

Step 4: Advanced Patterns

Caching Pattern:

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

async function getPost(slug: string) {
  // Try cache first
  const cached = await kv.get(`post:${slug}`);
  if (cached) return cached;

  // Fetch from database
  const post = await db.select().from(posts).where(eq(posts.slug, slug));

  // Cache for 1 hour
  await kv.setex(`post:${slug}`, 3600, post);

  return post;
}

Rate Limiting:

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

async function checkRateLimit(ip: string): Promise<boolean> {
  const key = `ratelimit:${ip}`;
  const limit = 10; // 10 requests
  const window = 60; // per 60 seconds

  const current = await kv.incr(key);

  if (current === 1) {
    // First request, set TTL
    await kv.expire(key, window);
  }

  return current <= limit;
}

// Usage in API route
export async function POST(request: Request) {
  const ip = request.headers.get('x-forwarded-for') || 'unknown';

  if (!await checkRateLimit(ip)) {
    return new Response('Rate limit exceeded', { status: 429 });
  }

  // Process request...
}

Session Management:

import { kv } from '@vercel/kv';
import { cookies } from 'next/headers';

export async function createSession(userId: number) {
  const sessionId = crypto.randomUUID();
  const sessionData = { userId, createdAt: Date.now() };

  // Store session for 7 days
  await kv.setex(`session:${sessionId}`, 7 * 24 * 3600, sessionData);

  // Set cookie
  cookies().set('session', sessionId, {
    httpOnly: true,
    secure: true,
    maxAge: 7 * 24 * 3600
  });

  return sessionId;
}

export async function getSession() {
  const sessionId = cookies().get('session')?.value;
  if (!sessionId) return null;

  return await kv.get(`session:${sessionId}`);
}

Pipeline (Batch Operations):

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

// Execute multiple commands in a single round-trip
const pipeline = kv.pipeline();

pipeline.set('user:1', { name: 'Alice' });
pipeline.incr('counter');
pipeline.get('config');

const results = await pipeline.exec();
// Returns: ['OK', 1, { ... }]

Step 5: Key Naming Conventions

Use Namespaces:

// ❌ Bad: No structure
await kv.set('123', data);

// ✅ Good: Clear namespace
await kv.set('user:123', data);
await kv.set('post:abc:views', 100);
await kv.set('cache:homepage:en', html);

Naming Patterns:

• user:{id}:profile - User profile data
• post:{slug}:views - View counter for post
• cache:{page}:{locale} - Cached page content
• session:{token} - Session data
• ratelimit:{ip}:{endpoint} - Rate limit tracking
• lock:{resource} - Distributed locks

Critical Rules

Always Do

✅ Set TTL for temporary data - Avoid memory leaks and stale data

✅ Use namespaced keys - user:123 not 123 (prevents collisions)

✅ Handle null returns - Non-existent keys return null

✅ Use pipeline for multiple operations - Reduces latency (single round-trip)

✅ Serialize JSON-compatible data only - No functions, circular references, etc.

✅ Use SETNX for distributed locks - Prevents race conditions

✅ Monitor command usage - Stay within free tier limits (30K commands/month)

✅ Use read-only token for public reads - Better security

Never Do

❌ Never store sensitive data without encryption - KV is not encrypted at rest by default

❌ Never forget to set TTL - Keys without TTL stay forever (memory leak)

❌ Never use generic key names - data, cache, temp will collide

❌ Never store large values (>1MB) - Use Vercel Blob for large files

❌ Never use KV as primary database - It's a cache, not persistent storage

❌ Never exceed rate limits - 30K commands/month on free tier

❌ Never assume strong durability - KV is for ephemeral data, not critical data

❌ Never commit .env.local - Contains KV tokens (add to .gitignore)

Known Issues Prevention

This skill prevents 10 documented issues:

Issue #1: Missing Environment Variables

Error: Error: KV_REST_API_URL is not defined or KV_REST_API_TOKEN is not defined *