---
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/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.'
title: runtime-cache
canonical_url: https://skilld.dev/gh/vercel/vercel-plugin/runtime-cache
last_updated: 2026-11-14T03:01:59.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [.vercel.approvers](https://skilld.dev/api/skills-raw/vercel/vercel-plugin/runtime-cache/.vercel.approvers).
>
> If the user asked to install this Skill, run `npx skilld install vercel/vercel-plugin/runtime-cache`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/runtime-cache`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/vercel/vercel-plugin/runtime-cache) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/runtime-cache`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/runtime-cache --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/runtime-cache --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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

```ts
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

```ts
const cache = getCache({
  namespace: 'api',                    // prefix for keys
  namespaceSeparator: '$',             // separator (default)
  keyHashFunction: (key) => sha256(key), // custom key hashing
});
```

### Full Example (Framework-Agnostic)

```ts
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

```ts
'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):

```ts
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`)

```ts
// next.config.ts
const nextConfig: NextConfig = { cacheComponents: true };
```

```ts
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

```bash
# 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:

```ts
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

- 📖 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/caching/cdn-cache/purge
