Agent skill

vercel-kv

View SKILL.md on GitHub Repository
Stars 109
Forks 14

Install this agent skill to your Project

npx add-skill https://github.com/secondsky/claude-skills/tree/main/plugins/vercel-kv/skills/vercel-kv

SKILL.md

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', 3600, { userId: 123 });

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

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

Atomic Operations:

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

Multiple Keys:

typescript
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

bash
# 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

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

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

Official Documentation

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!

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

secondsky/claude-skills

skill-name

[TODO: Write comprehensive description in third-person. Start with "This skill provides..." or "This skill should be used when..."] [TODO: Add "Use when" scenarios - specific situations where Claude should use this skill] [TODO: Add keywords - technologies, use cases, error messages that should trigger this skill]

109 14
Explore
secondsky/claude-skills

websocket-implementation

Implements real-time WebSocket communication with connection management, room-based messaging, and horizontal scaling. Use when building chat systems, live notifications, collaborative tools, or real-time dashboards.

109 14
Explore
secondsky/claude-skills

ai-sdk-ui

109 14
Explore
secondsky/claude-skills

bun-nextjs

This skill should be used when the user asks about "Next.js with Bun", "Bun and Next", "running Next.js on Bun", "Next.js development with Bun", "create-next-app with Bun", or building Next.js applications using Bun as the runtime.

109 14
Explore
secondsky/claude-skills

bun-sqlite

Use for bun:sqlite, SQLite operations, prepared statements, transactions, and queries.

109 14
Explore
secondsky/claude-skills

bun-sveltekit

Use when building or running SvelteKit apps on Bun, including SSR, adapters, and Bun-specific APIs

109 14
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results