vercel-kv
Vercel KV (Redis-compatible key-value storage via Upstash). Use for Next.js caching, sessions, rate limiting, TTL data storage, or encountering KV_REST_API_URL errors, rate limit issues, JSON serialization errors. Provides strong consistency vs eventual consistency.
- License 许可
- MIT
- 最近更新
- 2026-11-08
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- vercel-kv
- license
- MIT
- metadata
- { "keywords": [ "vercel kv", "@vercel/kv", "vercel redis", "upstash vercel", "kv vercel", "redis vercel edge", "key-value vercel", "vercel cache", "vercel sessions", "vercel rate limit", "redis upstash", "kv storage", "edge kv", "serverless redis", "vercel ttl", "vercel expire", "kv typescript", "next.js kv", "server actions kv", "edge runtime kv" ] }
- description
- Vercel KV (Redis-compatible key-value storage via Upstash). Use for Next.js caching, sessions, rate limiting, TTL data storage, or encountering KV_REST_API_URL errors, rate limit issues, JSON serialization errors. Provides strong consistency vs eventual consistency.
02 资源文件 7
- 资产文件assets/example-template.txt416 B
- 参考文档references/common-patterns.md8.7 KB
- 参考文档references/known-issues.md6.1 KB
- 脚本scripts/example-script.sh302 B
- 参考文档templates/package.json506 B
- 脚本templates/session-management.ts8.3 KB
- 脚本templates/simple-rate-limiting.ts9.1 KB
03 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
# 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!
04 同仓库更多 Skills
vss-summarize-video
Use to summarize a recorded video via the LVS summarization microservice (HITL-gated) with a VLM fallback. Not for report generation or live RTSP captioning.
vss-setup-video-analytics-api
Use to deploy the vss-video-analytics-api REST service standalone (config-source, data-log bind, Elasticsearch, optional Kafka). Not for full warehouse deploy.
vss-setup-behavior-analytics
Use to deploy the vss-behavior-analytics service standalone (entrypoint, config-source, optional calibration). Not for the full warehouse deploy.
vss-search-archive
Use this skill to run top-level VSS fusion search on archived video, or to ingest video files / RTSP streams for search. Do NOT use for ad-hoc visual Q&A (use vss-ask-video), live captioning (use vss-deploy-dense-captioning), or video summarization and reports (use vss-summarize-video).
vss-query-analytics
Use this skill when reading video-analytics metrics, incidents, alerts, and sensor data via the VA-MCP server (port 9901). Not for live VLM or incident-range narrative reports.
vss-manage-video-io-storage
Use to call the VIOS REST API (sensor list, timelines, clip extraction, snapshots, add/delete sensors and streams). Not for VLM inference or search.