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.

Quality

70%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/vercel/skills/runtime-cache/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 (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

Repository: openai/plugins
Path: plugins/vercel/skills/runtime-cache/SKILL.md
Commit: 11c74d6

Last updated: 8 days ago
First committed: 4 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.