Agent Skills
› fanfan-de/anybox
› runtime-cache
runtime-cache
GitHub指导使用 Vercel Runtime Cache API，涵盖 per-region KV 存储、标签失效及 CDN 清除。适用于函数、中间件和构建中的缓存策略实现。
Trigger Scenarios
需要实现 Vercel 运行时缓存
处理缓存标签失效或更新
优化服务器less函数的数据缓存策略
需要跨层清除 CDN 和运行时缓存
Install
npx skills add fanfan-de/anybox --skill runtime-cache -g -y
SKILL.md
Frontmatter
{
"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."
}
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
Version History
- 08dc189 Current 2026-07-05 19:11
