Cache Components in Next.js – Partial Prerendering, Streaming, and Fine-Grained Caching

Introduction

Next.js Cache Components offer a new way to balance static and dynamic rendering. Instead of choosing between fast static pages or fresh dynamic ones, you can now cache parts of your UI and data while still rendering dynamic content on demand. This is achieved through Partial Prerendering (PPR), Suspense boundaries, and the 'use cache' directive.

How Cache Components Work

With Cache Components enabled, all routes are treated as dynamic by default. However, you can mark specific data or components as cacheable, allowing them to be included in the pre-rendered shell. This shell is sent instantly to the client, while dynamic parts stream in as they become ready.

To enable Cache Components, set cacheComponents: true in your next.config.js.

Three Tools for Control

1. Suspense for Runtime Data

Wrap components that use runtime APIs (e.g., cookies(), headers(), searchParams) in <Suspense> to allow the rest of the page to be pre-rendered:

<Suspense fallback={<Skeleton />}>
  <UserProfile />
</Suspense>

2. Suspense for Dynamic Data

Wrap components that fetch data or query databases in Suspense to enable streaming:

async function DynamicContent() {
  const res = await fetch('https://api.example.com/posts')
  const { posts } = await res.json()
  return <div>{/* ... */}</div>
}

3. Cached Data with use cache

Use 'use cache' in Server Components or utility functions to cache their output:

export async function getProducts() {
  'use cache'
  const data = await db.query('SELECT * FROM products')
  return data
}

Streaming and Partial Rendering

Streaming splits the route into chunks and sends them to the client as they become ready. This improves time-to-first-byte and time-to-interactive. The static shell is sent immediately, while dynamic chunks hydrate progressively.

Using cacheLife

You can define how long a cached component or function should live:

export default async function Page() {
  'use cache'
  cacheLife('hours')
  return <div>...</div>
}

Caveats and Best Practices

• Arguments to cached functions must be serializable.
• You can accept unserializable values as long as you don’t introspect them.
• Don’t pass runtime data (e.g., cookies, headers) into cached functions.

Tagging and Revalidating Cached Data

Using updateTag

Use updateTag to expire and refresh cached data immediately:

export async function getCart() {
  'use cache'
  cacheTag('cart')
  // fetch cart data
}

export async function updateCart(itemId) {
  'use server'
  // update cart
  updateTag('cart')
}

Using revalidateTag

Use revalidateTag for stale-while-revalidate behavior:

export async function getPosts() {
  'use cache'
  cacheTag('posts')
  // fetch posts
}

export async function createPost(post) {
  'use server'
  // create post
  revalidateTag('posts', 'max')
}

Conclusion

Cache Components in Next.js give developers fine-grained control over rendering and caching. By combining Suspense, streaming, and the 'use cache' directive, you can build applications that are both fast and dynamic — delivering instant UI while keeping data fresh.