rembrembdocs
← nextjsoriginal source ↗

Caching and Revalidating (Previous Model)

Last updated April 23, 2026

This guide assumes you are not using Cache Components which was introduced in version 16 under the cacheComponents flag.

Caching fetch requests

By default, fetch requests are not cached. You can cache individual requests by setting the cache option to 'force-cache'.

app/page.tsx

JavaScriptTypeScript

export default async function Page() {
  const data = await fetch('https://...', { cache: 'force-cache' })
}

See the fetch API reference to learn more.

unstable_cache for non-fetch functions

unstable_cache allows you to cache the result of database queries and other async functions that don't use fetch. Wrap unstable_cache around the function:

app/lib/data.ts

JavaScriptTypeScript

import { unstable_cache } from 'next/cache'
import { db } from '@/lib/db'
 
export const getCachedUser = unstable_cache(
  async (id: string) => {
    return db
      .select()
      .from(users)
      .where(eq(users.id, id))
      .then((res) => res[0])
  },
  ['user'], // cache key prefix
  {
    tags: ['user'],
    revalidate: 3600,
  }
)

The third argument accepts:

See the unstable_cache API reference to learn more.

Route segment config

You can configure caching behavior at the route level by exporting config options from a Page, Layout, or Route Handler.

dynamic

Change the dynamic behavior of a layout or page to fully static or fully dynamic.

layout.tsx | page.tsx | route.ts

JavaScriptTypeScript

export const dynamic = 'auto'
// 'auto' | 'force-dynamic' | 'error' | 'force-static'

fetchCache

This is an advanced option that should only be used if you specifically need to override the default behavior.

By default, Next.js will cache any fetch() requests that are reachable before any Request-time APIs are used and will not cache fetch requests that are discovered after Request-time APIs are used.

fetchCache allows you to override the default cache option of all fetch requests in a layout or page.

layout.tsx | page.tsx | route.ts

JavaScriptTypeScript

export const fetchCache = 'auto'
// 'auto' | 'default-cache' | 'only-cache'
// 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'
Cross-route segment behavior

Time-based revalidation

Use the next.revalidate option on fetch to revalidate data after a specified number of seconds:

app/page.tsx

JavaScriptTypeScript

export default async function Page() {
  const data = await fetch('https://...', { next: { revalidate: 3600 } })
}

For non-fetch functions, unstable_cache accepts a revalidate option in its configuration (see example above).

Route segment config revalidate

Set the default revalidation time for a layout or page. This option does not override the revalidate value set by individual fetch requests.

layout.tsx | page.tsx | route.ts

JavaScriptTypeScript

export const revalidate = false
// false | 0 | number

Good to know:

  • The revalidate value needs to be statically analyzable. For example revalidate = 600 is valid, but revalidate = 60 * 10 is not.
  • The revalidate value is not available when using runtime = 'edge'.
  • In Development, Pages are always rendered on-demand and are never cached. This allows you to see changes immediately without waiting for a revalidation period to pass.

Revalidation frequency

On-demand revalidation

To revalidate cached data after an event, use revalidateTag or revalidatePath in a Server Action or Route Handler.

Tagging cached data

Tag fetch requests with next.tags to enable on-demand cache invalidation:

app/lib/data.ts

JavaScriptTypeScript

export async function getUserById(id: string) {
  const data = await fetch(`https://...`, {
    next: { tags: ['user'] },
  })
}

For non-fetch functions, unstable_cache also accepts a tags option (see example above).

revalidateTag

Invalidate cached data by tag using revalidateTag:

app/lib/actions.ts

JavaScriptTypeScript

import { revalidateTag } from 'next/cache'
 
export async function updateUser(id: string) {
  // Mutate data
  revalidateTag('user')
}

revalidatePath

Invalidate all cached data for a specific route path using revalidatePath:

app/lib/actions.ts

JavaScriptTypeScript

import { revalidatePath } from 'next/cache'
 
export async function updateUser(id: string) {
  // Mutate data
  revalidatePath('/profile')
}

Deduplicating requests

If you are not using fetch (which is automatically memoized), and instead using an ORM or database directly, you can wrap your data access with the React cache function to deduplicate requests within a single render pass:

app/lib/data.ts

JavaScriptTypeScript

import { cache } from 'react'
import { db, posts, eq } from '@/lib/db'
 
export const getPost = cache(async (id: string) => {
  const post = await db.query.posts.findFirst({
    where: eq(posts.id, parseInt(id)),
  })
})

Preloading data

You can preload data by creating a utility function that you eagerly call above blocking requests. This lets you initiate data fetching early, so the data is already available by the time the component renders.

Combine the server-only package with React's cache to create a reusable preload utility:

utils/get-item.ts

JavaScriptTypeScript

import { cache } from 'react'
import 'server-only'
 
export const getItem = cache(async (id: string) => {
  // ...
})
 
export const preload = (id: string) => {
  void getItem(id)
}

Then call preload() before any blocking work so the data starts loading immediately:

app/item/[id]/page.tsx

JavaScriptTypeScript

import { getItem, preload, checkIsAvailable } from '@/lib/data'
 
export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  // Start loading item data
  preload(id)
  // Perform another asynchronous task
  const isAvailable = await checkIsAvailable()
 
  return isAvailable ? <Item id={id} /> : null
}
 
async function Item({ id }: { id: string }) {
  const result = await getItem(id)
  // ...
}

Was this helpful?