runtime-cache
Vercel Runtime Cache API guidance — ephemeral per-region key-value cache with tag-based invalidation. Shared across Functions, Routing Middleware, and Builds. Use when implementing caching strategies beyond framework-level caching.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 29
- Forks
- 156
01 前言 Front Matter
- name
- runtime-cache
- chainTo
- [ { "message": "@vercel/kv is sunset — loading Vercel Storage guidance for Upstash Redis migration.", "pattern": "from\\s+['\"\"]@vercel/kv['\"\"]", "targetSkill": "vercel-storage" }, { "message": "Direct Redis client detected — loading Vercel Storage guidance for Upstash Redis (serverless-native) integration.", "pattern": "from\\s+['\"\"]ioredis['\"\"]|new\\s+Redis\\(", "targetSkill": "vercel-storage" } ]
- metadata
- { "docs": [ "https://nextjs.org/docs/app/building-your-application/caching" ], "sitemap": "https://nextjs.org/sitemap.xml", "priority": 6, "bashPatterns": [ "\\bnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/functions\\b", "\\bpnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/functions\\b", "\\bbun\\s+(install|i|add)\\s+[^\\n]*@vercel/functions\\b", "\\byarn\\s+add\\s+[^\\n]*@vercel/functions\\b" ], "pathPatterns": [ "lib/cache/**", "src/lib/cache/**", "lib/cache.*", "src/lib/cache.*" ] }
- validate
- [ { "message": "Direct Redis/ioredis client detected. Use Upstash Redis (@upstash/redis) for serverless-native Redis with HTTP-based connections.", "pattern": "from\\s+['\"\"](redis|ioredis)['\"\"]|require\\s*\\(\\s*['\"\"](redis|ioredis)['\"\"]|new\\s+Redis\\(", "severity": "recommended", "upgradeWhy": "Replace direct Redis/ioredis with @upstash/redis for serverless-compatible HTTP-based Redis that works without persistent TCP connections.", "upgradeToSkill": "vercel-storage", "skipIfFileContains": "from\\s+['\"\"]\\@upstash/redis['\"\"]" } ]
- retrieval
- { "aliases": [ "cache api", "kv cache", "region cache", "tag invalidation" ], "intents": [ "add caching", "cache api response", "invalidate cache", "set up runtime cache" ], "entities": [ "Runtime Cache", "tag-based invalidation", "key-value", "cache" ] }
- description
- Vercel Runtime Cache API guidance — ephemeral per-region key-value cache with tag-based invalidation. Shared across Functions, Routing Middleware, and Builds. Use when implementing caching strategies beyond framework-level caching.
03 SKILL.md 正文
Vercel Runtime Cache API
You are an expert in the Vercel Runtime Cache — an ephemeral caching layer for serverless compute.
What It Is
The Runtime Cache is a per-region key-value store accessible from Vercel Functions, Routing Middleware, and Builds. It supports tag-based invalidation for granular cache control.
- Regional: Each Vercel region has its own isolated cache
- Isolated: Scoped per project AND per deployment environment (
previewvsproduction) - Persistent across deployments: Cached data survives new deploys; invalidation via TTL or
expireTag - Ephemeral: Fixed storage limit per project; LRU eviction when full
- Framework-agnostic: Works with any framework via
@vercel/functions
Key APIs
All APIs from @vercel/functions:
Basic Cache Operations
import { getCache } from '@vercel/functions';
const cache = getCache();
// Store data with TTL and tags
await cache.set('user:123', userData, {
ttl: 3600, // seconds
tags: ['users', 'user:123'], // for bulk invalidation
name: 'user-profile', // human-readable label for observability
});
// Retrieve cached data (returns value or undefined)
const data = await cache.get('user:123');
// Delete a specific key
await cache.delete('user:123');
// Expire all entries with a tag (propagates globally within 300ms)
await cache.expireTag('users');
await cache.expireTag(['users', 'user:123']); // multiple tags
Cache Options
const cache = getCache({
namespace: 'api', // prefix for keys
namespaceSeparator: ':', // separator (default)
keyHashFunction: (key) => sha256(key), // custom key hashing
});
Full Example (Framework-Agnostic)
import { getCache } from '@vercel/functions';
export default {
async fetch(request: Request) {
const cache = getCache();
const cached = await cache.get('blog-posts');
if (cached) {
return Response.json(cached);
}
const posts = await fetch('https://api.example.com/posts').then(r => r.json());
await cache.set('blog-posts', posts, {
ttl: 3600,
tags: ['blog'],
});
return Response.json(posts);
},
};
Tag Expiration from Server Action
'use server';
import { getCache } from '@vercel/functions';
export async function invalidateBlog() {
await getCache().expireTag('blog');
}
CDN Cache Purging Functions
These purge across all three cache layers (CDN + Runtime Cache + Data Cache):
import { invalidateByTag, dangerouslyDeleteByTag } from '@vercel/functions';
// Stale-while-revalidate: serves stale, revalidates in background
await invalidateByTag('blog-posts');
// Hard delete: next request blocks while fetching from origin (cache stampede risk)
await dangerouslyDeleteByTag('blog-posts', {
revalidationDeadlineSeconds: 3600,
});
Important distinction:
cache.expireTag()— operates on Runtime Cache onlyinvalidateByTag()/dangerouslyDeleteByTag()— purges CDN + Runtime + Data caches
Next.js Integration
Next.js 16+ (use cache: remote)
// next.config.ts
const nextConfig: NextConfig = { cacheComponents: true };
import { cacheLife, cacheTag } from 'next/cache';
async function getData() {
'use cache: remote' // stores in Vercel Runtime Cache
cacheTag('example-tag')
cacheLife({ expire: 3600 })
return fetch('https://api.example.com/data').then(r => r.json());
}
'use cache'(no: remote) — in-memory only, ephemeral per instance'use cache: remote'— stores in Vercel Runtime Cache
Next.js 16 Invalidation APIs
| Function | Context | Behavior |
|---|---|---|
updateTag(tag) |
Server Actions only | Immediate expiration, read-your-own-writes |
revalidateTag(tag, 'max') |
Server Actions + Route Handlers | Stale-while-revalidate (recommended) |
revalidateTag(tag, { expire: 0 }) |
Route Handlers (webhooks) | Immediate expiration from external triggers |
Important: Single-argument revalidateTag(tag) is deprecated in Next.js 16. Always pass a cacheLife profile as the second argument.
Runtime Cache vs ISR Isolation
- Runtime Cache tags do NOT apply to ISR pages
cache.expireTagdoes NOT invalidate ISR cache- Next.js
revalidatePath/revalidateTagdoes NOT invalidate Runtime Cache - To manage both, use same tag and purge via
invalidateByTag(hits all cache layers)
CLI Cache Commands
# Purge all cached data
vercel cache purge # CDN + Data cache
vercel cache purge --type cdn # CDN only
vercel cache purge --type data # Data cache only
vercel cache purge --yes # skip confirmation
# Invalidate by tag (stale-while-revalidate)
vercel cache invalidate --tag blog-posts,user-profiles
# Hard delete by tag (blocks until revalidated)
vercel cache dangerously-delete --tag blog-posts
vercel cache dangerously-delete --tag blog-posts --revalidation-deadline-seconds 3600
# Image invalidation
vercel cache invalidate --srcimg /images/hero.jpg
Note: --tag and --srcimg cannot be used together.
CDN Cache Tags
Add tags to CDN cached responses for later invalidation:
import { addCacheTag } from '@vercel/functions';
// Via helper
addCacheTag('product-123');
// Via response header
return Response.json(product, {
headers: {
'Vercel-CDN-Cache-Control': 'public, max-age=86400',
'Vercel-Cache-Tag': 'product-123,products',
},
});
Limits
| Property | Limit |
|---|---|
| Item size | 2 MB |
| Tags per Runtime Cache item | 64 |
| Tags per CDN item | 128 |
| Max tag length | 256 bytes |
| Tags per bulk REST API call | 16 |
Tags are case-sensitive and cannot contain commas.
Observability
Monitor hit rates, invalidation patterns, and storage usage in the Vercel Dashboard under Observability → Runtime Cache. The CDN dashboard (March 5, 2026) provides a unified view of global traffic distribution, cache performance metrics, a redesigned purging interface, and project-level routing — update response headers or rewrite to external APIs without triggering a new deployment. Project-level routes are available on all plans and take effect instantly.
When to Use
- Caching API responses or computed data across functions in a region
- Tag-based invalidation when content changes (CMS webhook → expire tag)
- Reducing database load for frequently accessed data
- Cross-function data sharing within a region
When NOT to Use
- Framework-level page caching → use Next.js Cache Components (
'use cache') - Persistent storage → use a database (Neon, Upstash)
- CDN-level full response caching → use
Cache-Control/Vercel-CDN-Cache-Controlheaders - Cross-region shared state → use a database
- User-specific data that differs per request
References
- 📖 docs: https://vercel.com/docs/runtime-cache
- 📖 changelog: https://vercel.com/changelog/introducing-the-runtime-cache-api
- 📖 CLI cache: https://vercel.com/docs/cli/cache
- 📖 CDN cache purging: https://vercel.com/docs/cdn-cache/purge
04 同仓库更多 Skills
business-data
暂无简介
workflow
Creates durable, resumable workflows using Vercel's Workflow SDK. Use when building workflows that need to survive restarts, pause for external events, retry on failure, or coordinate multi-step operations over time. Triggers on mentions of "workflow", "durable functions", "resumable", "workflow sdk", "queue", "event", "push", "subscribe", or step-based orchestration.
workflow
Vercel Workflow SDK expert guidance. Use when building durable workflows, long-running tasks, API routes or agents that need pause/resume, retries, step-based execution, or crash-safe orchestration with Vercel Workflow.
verification
Full-story verification — infers what the user is building, then verifies the complete flow end-to-end: browser → API → data → response. Triggers on dev server start and 'why isn't this working' signals.
vercel-storage
Vercel storage expert guidance — Blob, Global Config (formerly Edge Config), and Marketplace storage (Neon Postgres, Upstash Redis). Use when choosing, configuring, or using data storage with Vercel applications.
vercel-services
Configure and troubleshoot Vercel Services for multiple frontends and backends in one project. Use when composing a polyglot or multi-service application on one Vercel deployment; defining the `services` key, service-targeted rewrites, or service bindings in `vercel.json`; or running all services with `vercel dev`.