Getting Started
Core Concepts
Troubleshooting
Caching and revalidation help your application load instantly by storing the results of expensive operations, database queries, and page renders. Instead of recalculating data on every single request, the system serves saved copies and updates them progressively behind the scenes using incremental revalidation.
This guide explains how to manage your application's data lifecycles, clear outdated information on-demand, and use helper functions to control when and how your content gets refreshed.
You can structure your caching behavior using dedicated utilities available on the server.
When working with cached data or functions, you can configure how long items remain fresh before checking for updates.
Note
Functions like revalidateTag, revalidatePath, updateTag, and refresh are designed to be run strictly in server-side contexts, such as Server Actions or route handlers, to maintain reliable update lifecycles.
When underlying data changes (such as a database update), you can clear cached content instantly using tags or paths.
When creating reusable cache functions or fetching data, assign relevant string tags to group your cached items together.
import { unstable_cache } from 'next/cache';
const getCachedUser = unstable_cache(
async (userId: string) => {
return await db.users.findUnique({ where: { id: userId } });
},
['user-cache'],
{ tags: ['users'] }
);When a user performs an action that modifies the data, call the appropriate revalidation helper to clear the tag:
import { updateTag } from 'next/cache';
async function updateUserAction(userId: string, formData: FormData) {
'use server';
// Perform database updates here...
// Instantly invalidate the tag so subsequent requests fetch fresh data
updateTag('users');
}Tip
Group related data under shared cache tags. This allows you to invalidate dozens of individual cache entries with a single call to revalidateTag or updateTag.
Warning
Calling revalidation functions like updateTag, revalidateTag, or revalidatePath directly inside a regular render pass or inside a cached function is unsupported and will throw an error. Always execute revalidations outside of rendering logic, such as inside Server Actions or route handlers.