---
title: "Caching and Revalidation"
description: "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 reque..."
last_updated: "2026-09-23T10:57:21.229799+00:00"
canonical_url: "https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/core-concepts/caching-and-revalidation"
---

## Overview

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.

---

## Key Concepts

* **Cache Entry**: A saved copy of a rendered page, route response, or function result stored for fast retrieval.
* **Stale Data**: Content that has passed its designated age or revalidation timeframe. A stale entry may still be served to users temporarily while a fresh version is generated in the background (Stale-While-Revalidate).
* **Cache Tag**: A label assigned to cached items so you can clear or update multiple related data entries simultaneously.
* **Incremental Revalidation**: The ability to update specific pages or cached pieces of data without needing to rebuild or re-render the entire website.

---

## Managing and Controlling Cache Lifecycles

### Overview

You can structure your caching behavior using dedicated utilities available on the server.

### Controlling Data Expiration and Revalidation

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.

### Purging Content On-Demand

When underlying data changes (such as a database update), you can clear cached content instantly using tags or paths.

| Function | Purpose | Context Requirement |
| :--- | :--- | :--- |
| `revalidateTag` | Clears all cached items associated with a specific tag name. | Server-side contexts (can accept a cache profile or expire configuration). |
| `updateTag` | Immediately updates a tag for read-your-own-writes semantics. | Must be called from within a **Server Action**. |
| `revalidatePath` | Purges cached content for a specific URL path (optional types: `page` or `layout`). | Server-side contexts. |
| `refresh` | Refreshes client-side dynamic data caches without dropping server data. | Must be called from within a **Server Action**. |

---

## Step-by-Step Instructions: Revalidating Content

### 1. Tagging Your Data
When creating reusable cache functions or fetching data, assign relevant string tags to group your cached items together.

```typescript
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'] }
);
```

### 2. Triggering an On-Demand Update
When a user performs an action that modifies the data, call the appropriate revalidation helper to clear the tag:

```typescript
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');
}
```

---

## Tips and Warnings

> [!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.

## Related

- [Data Fetching Mutations](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/core-concepts/data-fetching-mutations)
- [Deployment and Hosting](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/how-to-guides/deployment-and-hosting)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/llms.txt) for all pages in this wiki.