/runtime-cache

name: runtime-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.
metadata:
  priority: 6
  docs:
    - "https://nextjs.org/docs/app/building-your-application/caching"
  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.'

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 (webho