runtime-cache

by vercel

Vercel Runtime Cache API guidance — ephemeral per-region key-value cache with tag-based invalidation. Shared across Functions, Routing Middleware, and Builds.… npx skills add https://github.com/vercel/vercel-plugin --skill runtime-cache Download ZIPGitHub207

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 (preview vs production)

• 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 only

• invalidateByTag() / 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.expireTag does NOT invalidate ISR cache

• Next.js revalidatePath / revalidateTag does 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-Control headers

• 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