next/cache

The next/cache module provides APIs for controlling cache behavior, including time-based and tag-based revalidation, ISR, and the new Next.js 15+ "use cache" directive support.

Import

import {
  revalidateTag,
  revalidatePath,
  updateTag,
  refresh,
  unstable_cache,
  cacheLife,
  cacheTag,
  noStore,
} from 'next/cache'

import type {
  CacheHandler,
  CacheHandlerValue,
  IncrementalCacheValue,
} from 'next/cache'

Cache Functions

revalidateTag

Revalidate cached data associated with a specific cache tag.

import { revalidateTag } from 'next/cache'

export async function revalidatePosts() {
  revalidateTag('posts')
}

tag

string

required

Cache tag to revalidate.

profile

string | { expire?: number }

Next.js 16+: cacheLife profile for stale-while-revalidate.

revalidateTag('posts', 'hours')  // Use 'hours' profile
revalidateTag('posts', { expire: 3600 })  // Custom expire time

Usage with fetch

// Tag a fetch request
const posts = await fetch('https://api.example.com/posts', {
  next: { tags: ['posts'] }
})

// Later: revalidate all 'posts' fetches
revalidateTag('posts')

Usage with unstable_cache

const getCachedPosts = unstable_cache(
  async () => getPosts(),
  ['posts-list'],
  { tags: ['posts'] }
)

// Later: revalidate all 'posts' cached functions
revalidateTag('posts')

revalidatePath

Revalidate cached data for a specific path.

import { revalidatePath } from 'next/cache'

export async function updatePost(id: string) {
  await db.posts.update(id)
  revalidatePath('/blog')
  revalidatePath(`/blog/${id}`)
}

path

string

required

Path to revalidate (e.g., /blog, /products/123).

type

'page' | 'layout'

Next.js 14+: Revalidate type.

'page' — Revalidate specific page
'layout' — Revalidate layout and all children

Example: Server Action

'use server'
import { revalidatePath } from 'next/cache'

export async function createPost(formData: FormData) {
  const post = await db.posts.create({
    title: formData.get('title'),
    content: formData.get('content'),
  })
  
  // Revalidate the blog list page
  revalidatePath('/blog')
  
  return { success: true, id: post.id }
}

updateTag

Expire and immediately refresh cached data for a tag (Next.js 16+).

import { updateTag } from 'next/cache'

export async function updatePost(id: string) {
  await db.posts.update(id)
  updateTag('posts')  // Expire immediately
}

Provides read-your-writes semantics: the cache entry is expired and fresh data is read within the same request, so users immediately see their changes.

tag

string

required

Cache tag to expire and refresh.

refresh

Refresh uncached (dynamic) data on the page (Next.js 16+).

import { refresh } from 'next/cache'

export async function markAsRead(notificationId: string) {
  await db.notifications.markAsRead(notificationId)
  refresh()  // Re-fetch dynamic data
}

Signals the client to re-fetch dynamic data without touching the cache. Useful for notification counts, live metrics, or status indicators.

noStore

Opt out of caching for the current component/function.

import { noStore } from 'next/cache'

export default async function RealTimePage() {
  noStore()  // Mark as dynamic
  
  const data = await getRealTimeData()
  return <div>{data.value}</div>
}

Equivalent to setting Cache-Control: no-store on the response. Also available as unstable_noStore().

unstable_cache

Wrap an async function with caching.

import { unstable_cache } from 'next/cache'

const getCachedUser = unstable_cache(
  async (id: string) => {
    return await db.users.findById(id)
  },
  ['user'],
  {
    tags: ['user'],
    revalidate: 3600  // 1 hour
  }
)

const user = await getCachedUser('123')

Parameters

(...args: any[]) => Promise<T>

required

Async function to wrap.

keyParts

string[]

Cache key components. Combined with serialized arguments to form the final key.

unstable_cache(
  (id) => getUser(id),
  ['user']  // Final key: unstable_cache:user:{"id":"123"}
)

options

object

Cache options.

interface UnstableCacheOptions {
  revalidate?: number | false  // Seconds, or false for no expiry
  tags?: string[]              // Cache tags for revalidation
}

Example: Cached API Call

import { unstable_cache } from 'next/cache'

const getCachedPosts = unstable_cache(
  async () => {
    const res = await fetch('https://api.example.com/posts')
    return res.json()
  },
  ['posts-api'],
  {
    revalidate: 60,  // Revalidate every 60 seconds
    tags: ['posts']
  }
)

export default async function BlogPage() {
  const posts = await getCachedPosts()
  return <PostList posts={posts} />
}

”use cache” APIs (Next.js 15+)

cacheLife

Set cache lifetime for a "use cache" function.

'use cache'
import { cacheLife } from 'next/cache'

export async function getPosts() {
  cacheLife('hours')  // Use 'hours' profile
  return await db.posts.findMany()
}

profile

string | CacheLifeConfig

required

Built-in profile name or custom config.Built-in profiles:

'default' — 15 min revalidate, ~49 day expire
'seconds' — 30s stale, 1s revalidate, 60s expire
'minutes' — 5 min stale, 1 min revalidate, 1h expire
'hours' — 5 min stale, 1h revalidate, 1 day expire
'days' — 5 min stale, 1 day revalidate, 1 week expire
'weeks' — 5 min stale, 1 week revalidate, 1 month expire
'max' — 5 min stale, 1 month revalidate, 1 year expire

Custom config:

interface CacheLifeConfig {
  stale?: number      // Client cache duration (seconds)
  revalidate?: number // Server revalidation interval (seconds)
  expire?: number     // Max staleness before deopt (seconds)
}

Example: Custom Profile

'use cache'
import { cacheLife } from 'next/cache'

export async function getPopularPosts() {
  cacheLife({
    stale: 60,         // Client can cache for 60s
    revalidate: 300,   // Server refreshes every 5 min
    expire: 3600       // Hard expire after 1 hour
  })
  
  return await db.posts.findMany({
    orderBy: { views: 'desc' }
  })
}

cacheTag

Tag a "use cache" function for revalidation.

'use cache'
import { cacheTag } from 'next/cache'

export async function getPosts() {
  cacheTag('posts', 'blog')
  return await db.posts.findMany()
}

// Later: revalidate
revalidateTag('posts')

...tags

string[]

required

Tags to attach to the cached result.

Cache Handler

Plug in a custom cache backend (Redis, DynamoDB, Cloudflare KV, etc.).

Interface

import type { CacheHandler, IncrementalCacheValue } from 'next/cache'

class MyCacheHandler implements CacheHandler {
  async get(key: string): Promise<CacheHandlerValue | null> {
    // Return cached entry or null
  }
  
  async set(key: string, data: IncrementalCacheValue | null): Promise<void> {
    // Store cache entry
  }
  
  async revalidateTag(tags: string | string[]): Promise<void> {
    // Invalidate entries with matching tags
  }
}

Usage

import { setCacheHandler } from 'next/cache'
import { MyCacheHandler } from './cache'

// At server startup
setCacheHandler(new MyCacheHandler())

Built-in Handlers

MemoryCacheHandler

In-memory cache (default). Not shared across workers/instances.

import { MemoryCacheHandler } from 'next/cache'

Cloudflare KV Handler

vinext includes a KV-backed handler for Cloudflare Workers:

import { createKVCacheHandler } from 'vinext/cache/kv'

const handler = createKVCacheHandler(env.CACHE_KV)
setCacheHandler(handler)

CacheHandlerValue Type

interface CacheHandlerValue {
  lastModified: number
  age?: number
  cacheState?: 'stale' | 'fresh'
  value: IncrementalCacheValue | null
}

type IncrementalCacheValue =
  | CachedFetchValue
  | CachedAppPageValue
  | CachedRouteValue
  | CachedImageValue

ISR (Incremental Static Regeneration)

vinext supports time-based and tag-based ISR:

Time-Based Revalidation

// Revalidate every 60 seconds
export const revalidate = 60

export default async function Page() {
  const posts = await getPosts()
  return <PostList posts={posts} />
}

Tag-Based Revalidation

export default async function Page() {
  const posts = await fetch('https://api.example.com/posts', {
    next: { tags: ['posts'] }
  })
  
  return <PostList posts={await posts.json()} />
}

// In a Server Action:
import { revalidateTag } from 'next/cache'

export async function createPost() {
  await db.posts.create(...)
  revalidateTag('posts')
}

Stale-While-Revalidate

vinext’s ISR layer implements SWR:

Fresh: Serve cached entry immediately
Stale: Serve stale entry, trigger background revalidation
Expired: Return null (or skip cache)

Cache Deduplication

Multiple concurrent requests for the same cache key are deduplicated:

// Only one fetch occurs, even if called 10 times simultaneously
const promises = Array.from({ length: 10 }, () => getCachedPosts())
await Promise.all(promises)

Limitations

Cache key collisions: If two functions use the same keyParts and arguments, they share a cache entry. Use unique keys.

Serialization: Arguments and return values are JSON-serialized. Functions, Symbols, and undefined are not supported.

Server-only: All cache APIs are server-side only. Calling them in client components will throw.

Source

View source code → Implementation: /home/daytona/workspace/source/packages/vinext/src/shims/cache.ts

CLI

Module Shims

Configuration

Cloudflare

Import

Cache Functions

revalidateTag

Usage with fetch

Usage with unstable_cache

revalidatePath

Example: Server Action

updateTag

refresh

noStore

unstable_cache

Parameters

Example: Cached API Call

”use cache” APIs (Next.js 15+)

cacheLife

Example: Custom Profile

cacheTag

Cache Handler

Interface

Usage

Built-in Handlers

MemoryCacheHandler

Cloudflare KV Handler

CacheHandlerValue Type

ISR (Incremental Static Regeneration)

Time-Based Revalidation

Tag-Based Revalidation

Stale-While-Revalidate

Cache Deduplication

Limitations

Source

Build docs developers (and LLMs) love

CLI

Module Shims

Configuration

Cloudflare

Documentation Index

​Import

​Cache Functions

​revalidateTag

​Usage with fetch

​Usage with unstable_cache

​revalidatePath

​Example: Server Action

​updateTag

​refresh

​noStore

​unstable_cache

​Parameters

​Example: Cached API Call

​”use cache” APIs (Next.js 15+)

​cacheLife

​Example: Custom Profile

​cacheTag

​Cache Handler

​Interface

​Usage

​Built-in Handlers

​MemoryCacheHandler

​Cloudflare KV Handler

​CacheHandlerValue Type

​ISR (Incremental Static Regeneration)

​Time-Based Revalidation

​Tag-Based Revalidation

​Stale-While-Revalidate

​Cache Deduplication

​Limitations

​Source

Build docs developers (and LLMs) love

Import

Cache Functions

revalidateTag

Usage with fetch

Usage with unstable_cache

revalidatePath

Example: Server Action

updateTag

refresh

noStore

unstable_cache

Parameters

Example: Cached API Call

”use cache” APIs (Next.js 15+)

cacheLife

Example: Custom Profile

cacheTag

Cache Handler

Interface

Usage

Built-in Handlers

MemoryCacheHandler

Cloudflare KV Handler

CacheHandlerValue Type

ISR (Incremental Static Regeneration)

Time-Based Revalidation

Tag-Based Revalidation

Stale-While-Revalidate

Cache Deduplication

Limitations

Source