P-1 — Advanced Data Fetching: Patterns, Caching, and Control

React.cache() deduplicates within a request. unstable_cache persists results across requests — a proper server-side query cache.

// lib/posts.ts
import { unstable_cache } from 'next/cache';
 
export const getCachedPosts = unstable_cache(
  async () => {
    // This database query runs once, then the result is cached
    return db.posts.findMany({
      where: { published: true },
      orderBy: { publishedAt: 'desc' },
    });
  },
  ['all-posts'],          // cache key array — must be unique
  {
    revalidate: 3600,     // revalidate every hour (like ISR)
    tags: ['posts'],      // tag for on-demand invalidation
  }
);

// app/blog/page.tsx
 
export default async function BlogPage() {
  const posts = await getCachedPosts(); // pulls from cache, not the database
  return <PostList posts={posts} />;
}

The first call executes the database query and stores the result. Subsequent calls return the cached result without touching the database — for up to one hour (revalidate: 3600), or until you call revalidateTag('posts').

Cache Key Design

The cache key array uniquely identifies this cached entry. For parameterised queries, include the parameter in the key:

export const getCachedPost = unstable_cache(
  async (slug: string) => db.posts.findUnique({ where: { slug } }),
  ['post'],                          // base key
  { revalidate: 3600, tags: ['posts', `post-${slug}`] }
  // ⚠️ Problem: slug is a closure variable, not part of the key
);

The issue: unstable_cache uses the key array to identify the entry, but slug in the function body isn't part of the key — it's a closure. Two calls with different slugs both use the key ['post'] and you get cache collisions.

The correct pattern — include dynamic values in the key:

export function getCachedPost(slug: string) {
  return unstable_cache(
    async () => db.posts.findUnique({ where: { slug } }),
    ['post', slug],                      // ← slug is part of the key
    { revalidate: 3600, tags: ['posts', `post-${slug}`] }
  )();
}

Wrapping in a function and calling immediately ensures each unique slug gets its own cache entry.

---

On-Demand Cache Invalidation

Time-based revalidation is fine for content that can be slightly stale. On-demand invalidation is for content that must be fresh immediately after a mutation.

// app/actions/posts.ts (Server Action)
'use server';
 
import { revalidateTag, revalidatePath } from 'next/cache';
 
export async function publishPost(postId: string) {
  await db.posts.update({
    where: { id: postId },
    data: { published: true, publishedAt: new Date() },
  });
 
  // Invalidate the cached post list and this specific post
  revalidateTag('posts');
  revalidateTag(`post-${postId}`);
}

After publishPost runs, the next request for any data tagged 'posts' re-executes the query and caches the fresh result. The previously cached stale data is gone.

revalidatePath vs revalidateTag

// Invalidate all cached data for a specific URL path
revalidatePath('/blog');          // invalidates /blog
revalidatePath('/blog', 'page'); // invalidates the page at /blog
revalidatePath('/blog', 'layout'); // invalidates the layout at /blog (and all pages under it)
 
// Invalidate all cached data with a specific tag
revalidateTag('posts');           // invalidates across all paths tagged 'posts'

revalidatePath is URL-scoped. revalidateTag is data-scoped. Prefer revalidateTag — it's more precise and doesn't accidentally invalidate cached data on unrelated pages that happen to use the same path.

The rule: tag your cached data at the entity level ('posts', 'user-${id}', 'product-${id}') and invalidate by tag when that entity changes. Use revalidatePath for the rare case where you need to force a full page regeneration regardless of what data changed.

---

What Triggers Dynamic Rendering

This is the knowledge that saves you from accidentally making static pages dynamic. The following functions, when called anywhere in the Server Component render chain, opt the entire route into dynamic (per-request) rendering:

The key insight: these are transitive. If ComponentA is static but calls a function that calls cookies() five layers deep, ComponentA's entire route becomes dynamic. Note that Math.random()/Date.now() are not on this list — Next.js doesn't scan for generic non-determinism, so calling either in an otherwise-static component doesn't make the route dynamic; it just bakes a stale value into the static HTML at build time (see F-9 for the full explanation of this trap).

// ❌ Accidentally dynamic — cookies() buried in a utility
export default async function ProductPage() {
  const product = await getProduct();       // reads from DB — fine
  const userCurrency = await getCurrency(); // internally calls cookies() — makes page dynamic!
  return <Product product={product} currency={userCurrency} />;
}

// ✅ Isolate the dynamic concern to a Client Component or Suspense boundary
export default async function ProductPage({ params }) {
  const { id } = await params;
  const product = await getProduct(id);
 
  return (
    <>
      <ProductDetail product={product} />
      {/* Currency is user-specific — isolate it */}
      <Suspense fallback={<PriceSkeleton />}>
        <LocalisedPrice productId={id} />  {/* This component reads cookies — only this subtree is dynamic */}
      </Suspense>
    </>
  );
}

Suspense boundaries create dynamic "holes" in an otherwise static page. The static shell is served from the CDN; only the dynamic holes hit the server. This is the foundation of Partial Prerendering, which A-4 covers in depth.

---

connection() — Explicit Dynamic Signal

Next.js 15 introduced connection() as the explicit way to tell the framework "this route must be dynamic and I'm intentional about it":

import { connection } from 'next/server';
 
export default async function LiveDashboard() {
  await connection(); // ← explicitly opts into dynamic rendering
 
  const liveMetrics = await getLiveMetrics();
  return <MetricsDashboard metrics={liveMetrics} />;
}

Before connection(), you'd use unstable_noStore() (deprecated in 15) or access headers() / cookies() as a side effect just to trigger dynamic rendering. connection() makes the intent explicit and readable.

---

Fetch Deduplication — How Next.js Handles Repeated Fetches

When multiple Server Components in the same render call fetch() with the same URL and options, Next.js deduplicates the request — only one HTTP call is made:

// ComponentA.tsx
const user = await fetch(`/api/users/${id}`);
 
// ComponentB.tsx — rendered in the same request
const user = await fetch(`/api/users/${id}`); // ← same URL — deduplicated

This deduplication only works for fetch(), not for database clients or arbitrary async functions. For those, use React.cache() as covered in F-4.

The deduplication is per-request — it doesn't persist across requests. It's purely for preventing redundant network calls within the same render pass.

---

Avoiding Waterfall in Layouts

A common pattern that silently creates waterfalls: layout fetching and page fetching happening sequentially.

app/dashboard/layout.tsx    ← fetches user session (50ms)
  └── app/dashboard/page.tsx ← fetches dashboard data (120ms)
 
Total: 170ms (sequential — layout completes before page starts fetching)

The layout's data fetching blocks the page's data fetching. For data that both the layout and the page need, fetch it once at the page level and pass it down as props — or use React.cache() so both can call the same function without doubling the database round-trip.

// lib/queries.ts
 
// Both layout.tsx and page.tsx can call this — only one DB query fires per request
export const getSession = cache(async () => {
  const token = (await cookies()).get('session')?.value;
  if (!token) return null;
  return verifyToken(token);
});

The layout and the page both call getSession(). Because it's wrapped in cache(), the database query executes once and both get the same memoised result.

---

The Data Fetching Hierarchy

Putting it all together into a decision framework:

For data that never changes (or changes only on deploy): → Fetch in a Server Component without any cache config. Next.js statically generates the page at build time.

For data that changes but can be stale for minutes or hours: → Use unstable_cache with a revalidate time. Data is cached across requests and refreshed periodically.

For data that needs immediate freshness after specific mutations: → Use unstable_cache with tags and call revalidateTag() in the relevant Server Actions.

For data that must be fresh on every request: → Access it without unstable_cache, use cache: 'no-store' on fetch calls, or call connection() to explicitly opt into dynamic rendering.

For data that's shared across multiple components in a single request: → Wrap the query function in React.cache() for deduplication.

For independent data sources on the same page: → Wrap each in a <Suspense> boundary so they load in parallel and stream independently.

---

Where We Go From Here

P-2 covers Server Actions — the mutation counterpart to everything you've learned about fetching. If P-1 is about getting data into your application efficiently, P-2 is about getting user intent back to the server efficiently: how Server Actions are compiled, useActionState for form state, useOptimistic for instant UI feedback before the server responds, and the after() API for post-response side effects like sending emails or analytics events without blocking the response.

The caching concepts from this module resurface in P-7 when we cover the use cache directive — Next.js 15's new first-class caching primitive that replaces unstable_cache and integrates directly with the React component model. P-1 builds the foundation that P-7 extends.

---