Understanding Next.js Caching Architecture

Next.js uses four caching mechanisms that work together. Understanding how these layers interact is necessary for building applications that balance speed and freshness.

Request Memoization

Request memoization is a React feature that automatically deduplicates fetch requests with the same URL and options during a single React render pass. It operates on the server and stores return values for the per-request lifecycle.

async function getProduct(id) {
  // Called multiple times, but executed only once per render
  const res = await fetch(`https://api.example.com/products/${id}`)
  return res.json()
}
// In your component tree
const product1 = await getProduct(123) // cache MISS - executes
const product2 = await getProduct(123) // cache HIT - returns memoized

The cache lasts the lifetime of a server request until the React component tree has finished rendering, and memoization only applies to the GET method in fetch requests.

Data Cache

The Data Cache persists the result of data fetches across incoming server requests and deployments on the server. This is the layer that stores actual data responses from your APIs or databases.

In Next.js 15, fetch requests are not cached by default. You must explicitly opt into caching with cache: 'force-cache' or next.revalidate.

// Opt into caching
async function getProducts() {
  return fetch('https://api.example.com/products', {
    cache: 'force-cache'
  })
}
// Time-based revalidation
async function getInventory() {
  return fetch('https://api.example.com/inventory', {
    next: { revalidate: 300 } // Revalidate every 5 minutes
  })
}
// Cache with tags for targeted invalidation
async function getCatalog() {
  return fetch('https://api.example.com/catalog', {
    cache: 'force-cache',
    next: { tags: ['catalog'] }
  })
}

Full Route Cache

The Full Route Cache stores rendered HTML and React Server Component Payload of statically rendered routes at build time on the server. This allows serving the cached route instead of rendering on the server for every request.

Only statically rendered routes are cached by default. Dynamic routes (using cookies(), headers(), searchParams) are rendered on each request. Revalidating the Data Cache automatically invalidates the Full Route Cache since render output depends on data.

Router Cache

The Router Cache is an in-memory, client-side cache that stores the React Server Component Payload in the browser. It reduces server requests during navigation and is controlled by staleTimes.

Invalidation happens when you call revalidatePath, revalidateTag in a Server Action, use cookies.set/cookies.delete, call router.refresh(), or the automatic invalidation period expires.

Understanding staleTime

The staleTimes configuration controls how long the client-side Router Cache considers data "fresh" before needing to revalidate. The Vercel team designed this to reduce unnecessary re-renders and server requests, improving performance for data that doesn't require immediate freshness.

This works well for content where staleness is acceptable—like comments on a blog post. However, for applications requiring immediate data accuracy (like dashboards, inventory systems, or collaborative tools), staleTimes can be problematic.

How staleTime Works

When you navigate between pages, Next.js checks if the cached route is still within its stale time:

Within stale time: Route served instantly from cache
After stale time: Next.js fetches fresh data from server

// next.config.js
const nextConfig = {
  experimental: {
    staleTimes: {
      dynamic: 30,   // Dynamic routes stay fresh for 30 seconds -- Default: 0s
      static: 300    // Static routes stay fresh for 5 minutes -- Default 180s
    }
  }
}

Important considerations:

The client enforces a minimum stale time of 30 seconds for prefetched data - prefetch prop on Link or router.prefetch
Back/forward navigation still preserves the cache (similar to browser bfcache)
Setting stale time to 0 doesn't disable caching entirely for shared layouts
This only affects the Router Cache, not the Data Cache

The staleTime Problem

When one user updates data, other users viewing the same page won't see the changes until their Router Cache expires based on the staleTimes configuration.

Example:

// User A is viewing /products page
// User B updates a product
'use server'
export async function updateProduct(id, data) {
  await fetch(`https://api.example.com/products/${id}`, {
    method: 'PATCH',
    body: JSON.stringify(data)
  })
  revalidateTag('products') // Clears server-side Data Cache
}
// User B sees changes immediately
// User A still sees old data for up to 30 seconds

This happens because the Router Cache on User A's browser continues serving cached data until the staleTimes period expires.

Solutions

Solution 1: Configure staleTimes globally

Set staleTimes to 0 for all routes:

// next.config.js
const nextConfig = {
  experimental: {
    staleTimes: {
      dynamic: 0,  // Fetch fresh data on navigation
      static: 0
    }
  }
}

Note: The client still enforces a minimum 30-second stale time for prefetched data.

Solution 2: Use cacheLife for per-route control

For more granular control, use cacheLife to configure caching behavior per route:

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

export default async function DashboardPage() {
  cacheLife('minutes') // Use shorter cache lifetime for this route
  const data = await getData()
  return <Dashboard data={data} />
}

Define custom cache profiles:

// next.config.js
const nextConfig = {
  cacheLife: {
    realtime: {
      stale: 0,
      revalidate: 30,
      expire: 60
    },
    frequent: {
      stale: 60,
      revalidate: 300,
      expire: 3600
    }
  }
}

Use custom profiles in your pages:

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

export default async function InventoryPage() {
  cacheLife('realtime')
  const data = await getData()
  return <Dashboard data={data} />
}

What Are Server Actions?

Server Actions are asynchronous functions that run on the server and can be called from Client or Server Components. They're marked with the 'use server' directive and provide a server-side alternative to client-side data fetching libraries like React Query.

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

export async function updateProduct(id, data) {
  // Call your external REST API
  await fetch(`${process.env.API_URL}/products/${id}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data)
  })
  // Invalidate cache (similar to React Query's invalidateQueries)
  revalidateTag('products')
}

Key characteristics:

Run exclusively on the server
Automatically handle serialization and CSRF protection
Use only the POST HTTP method
Can access server-only resources (environment variables, cookies)
Integrate with Next.js caching for automatic revalidation

Using Server Actions for CRUD Operations

Server Actions work well for Create, Update, and Delete operations. For Read operations (GET requests), create separate functions without the 'use server' directive and call them in async Server Components.

File Structure

Create two separate files:

actions.ts - For mutations (CREATE, UPDATE, DELETE) with 'use server'
queries.ts - For read operations (GET) without 'use server'

Cache Revalidation Strategies

After mutating data through your external REST API, you need to invalidate the cache so users see fresh data. Next.js provides three main revalidation methods.

revalidateTag

revalidateTag invalidates cache entries associated with a specific tag. Use this when you want to invalidate related data across multiple routes.

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

export async function updateProduct(id, data) {
  const res = await fetch(`${process.env.API_URL}/products/${id}`, {
    method: 'PATCH',
    body: JSON.stringify(data)
  })
  // error handling
  // ...
  
  // Invalidate all cache entries with these tags
  revalidateTag('products')           // Invalidates product lists
  revalidateTag(`product-${id}`)      // Invalidates this specific product
  
  return res
}

Tag your fetch requests in your read functions:

// queries.ts
export async function getProducts() {
  const res = fetch(`${process.env.API_URL}/products`, {
    cache: 'force-cache',
    next: { tags: ['products'] }  // Tag for invalidation
  })
  // ...
}

export async function getProduct(id) {
  const res = fetch(`${process.env.API_URL}/products/${id}`, {
    cache: 'force-cache',
    next: { tags: ['products', `product-${id}`] } // Multiple tags
  })
  // ...
}

revalidatePath

revalidatePath invalidates all cache entries for a specific route path. Use this when you want to refresh everything on a particular page.

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

export async function updateProduct(id, data) {
  const res = await fetch(`${process.env.API_URL}/products/${id}`, {
    method: 'PATCH',
    body: JSON.stringify(data)
  })
  // error handling
  // ...
  
  // Invalidate all data on the settings page
  revalidatePath('/settings')
  // Invalidate a page and all its nested pages
  revalidatePath('/dashboard', 'layout')
}

updateTag

updateTag immediately expires cache entries, forcing a fresh fetch on the next request. Unlike revalidateTag which marks data as stale but can serve it while revalidating, updateTag ensures no stale data is served.

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

export async function updateProduct(id, data) {
  const res = await fetch(`${process.env.API_URL}/products/${id}`, {
    method: 'PATCH',
    body: JSON.stringify(data)
  })
  // error handling
  // ...
  
  // Immediately expire - user must see their new order
  updateTag('orders')
  updateTag(`user-orders-${orderData.userId}`)
  return order
}

Key differences:

revalidateTag: Marks cache as stale, serves stale data while revalidating in background
updateTag: Immediately expires cache, forces fresh fetch
revalidatePath: Invalidates entire route path

Server Actions: One Round Trip Advantage

When using Server Actions, revalidation happens in a single round trip between client and server. This is different from traditional approaches where you'd make a mutation request, wait for response, then trigger cache invalidation separately.

Traditional REST API approach (two round trips):

// Client makes mutation request
const response = await fetch(`${process.env.API_URL}/products/${id}`, {
  method: 'PATCH',
  body: JSON.stringify(data)
})
// ...

// Then client triggers cache invalidation
queryClient.invalidateQueries(['products'])

Server Actions approach (one round trip):

'use server'
export async function createProduct(data) {
  // 1. Mutate data on external API
  const res = await fetch(`${process.env.API_URL}/products/${id}`, {
    method: 'PATCH',
    body: JSON.stringify(data)
  })
  // error handling
  // ...
  
  // 2. Invalidate cache on server
  revalidateTag('products')
  // Both happen server-side in one client request
  return res
}
// Client just calls the action once
await createProduct(data)

The client makes one request to the Server Action, which handles both the mutation and cache invalidation on the server. This reduces network overhead and ensures cache invalidation happens automatically after every mutation.

Key Takeaways

Separate concerns: Use 'use server' for mutations (CREATE, UPDATE, DELETE), keep GET requests in separate files without the directive
Cache with tags: Use hierarchical tags like products and product-${id} for flexible cache invalidation
Invalidate after mutations: Always call revalidateTag / revalidatePath / updateTag after data changes to clear cached data
Call reads directly: In Server Components, call read functions directly without wrapping them in Server Actions
Understand staleTimes: Configure based on your freshness requirements—use lower values or cacheLife for data-critical applications

Server Actions provide a server-side alternative to React Query for managing external REST API connections in Next.js, with built-in caching and revalidation mechanisms.