Index of every page on this site: llms.txt
All skills
vercel avatar

/runtime-cache

@250769d official
by vercelvercel/vercel-plugin340 stars
82
Run it yourself

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.

  • 2 files
  • 9.2 KB
  • Updated last week
  • GitHub
Use this Skill: https://skilld.dev/gh/vercel/vercel-plugin/runtime-cache

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈62 tokens for metadata: the name and description. ≈1.8k when used: this file.

Description uses 3.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈247 characters, or 3.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 deployment environment (preview vs production); scoped per project on Pro/Enterprise, but shared across all projects on a Hobby team
  • Persistent across deployments: Cached data survives new deploys (except Next.js 16 use cache: remote entries, keyed per build); 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 null)
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 + Runtime + Data cache
vercel cache purge --type cdn         # CDN only
vercel cache purge --type data        # Runtime + Data cache
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 128
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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 250769d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last week
Other metadata
metadata
{
  "priority": 6,
  "docs": [
    "https://nextjs.org/docs/app/api-reference/directives/use-cache-remote"
  ],
  "sitemap": "https://nextjs.org/sitemap.xml",
  "pathPatterns": [
    "lib/cache/**",
    "src/lib/cache/**",
    "lib/cache.*",
    "src/lib/cache.*"
  ],
  "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"
  ]
}
validate
[
  {
    "pattern": "from\\s+['\"\"](redis|ioredis)['\"\"]|require\\s*\\(\\s*['\"\"](redis|ioredis)['\"\"]|new\\s+Redis\\(",
    "message": "Direct Redis/ioredis client detected. Use Upstash Redis (@upstash/redis) for serverless-native Redis with HTTP-based connections.",
    "severity": "recommended",
    "upgradeToSkill": "vercel-storage",
    "upgradeWhy": "Replace direct Redis/ioredis with @upstash/redis for serverless-compatible HTTP-based Redis that works without persistent TCP connections.",
    "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"
  ]
}
chainTo
[
  {
    "pattern": "from\\s+['\"\"]@vercel/kv['\"\"]",
    "targetSkill": "vercel-storage",
    "message": "@vercel/kv is sunset — loading Vercel Storage guidance for Upstash Redis migration."
  },
  {
    "pattern": "from\\s+['\"\"]ioredis['\"\"]|new\\s+Redis\\(",
    "targetSkill": "vercel-storage",
    "message": "Direct Redis client detected — loading Vercel Storage guidance for Upstash Redis (serverless-native) integration."
  }
]

README badge

README badge for vercel/vercel-plugin/runtime-cache