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

The Problem With Naive Data Fetching

Foundation-level data fetching — await db.query() in Server Components — is correct. But on a real application with multiple data sources, several failure modes emerge quickly:

Waterfall chains. Component A fetches user data, then renders Component B which fetches preferences, then renders Component C which fetches content. Three sequential round-trips when all three could have run in parallel.

No persistence across requests. React.cache() deduplicates within a single render, but the result is gone the moment the response is sent. Every request rebuilds the same data — a user's profile queried 10,000 times per minute means 10,000 database calls per minute, even when the profile hasn't changed.

Unintentional dynamic rendering. You introduce a cookie check in one small utility function and suddenly a page that was statically generated at build time is now server-rendering on every request. The build output flips from ○ to λ and your CDN cache hit rate collapses.

This module addresses all three.

Sequential vs Parallel — Recognising the Waterfall

The waterfall is the most common performance issue in App Router applications. It happens whenever you await multiple independent fetches sequentially:

tsx
// ❌ Sequential — total wait: A + B + C
export default async function ProfilePage({ params }) {
  const { id } = await params;
  const user = await getUser(id);               // 50ms
  const preferences = await getPreferences(id); // 80ms
  const recentActivity = await getActivity(id); // 120ms
  // Total wait: 250ms
}

These three queries don't depend on each other — getPreferences doesn't need the result of getUser. They should run in parallel:

tsx
// ✅ Parallel — total wait: max(A, B, C) = C = 120ms
export default async function ProfilePage({ params }) {
  const { id } = await params;
  const [user, preferences, recentActivity] = await Promise.all([
    getUser(id),
    getPreferences(id),
    getActivity(id),
  ]);
  // Total wait: 120ms — 52% faster
}

Spotting the pattern: any time you see multiple await statements at the top level of a Server Component or data function, ask: does the second await need the result of the first? If not, they can be parallelised.

Promise.allSettled for Graceful Degradation

Promise.all rejects if any promise rejects — one failed query takes down the whole fetch. For non-critical data, use Promise.allSettled:

tsx
const [userResult, activityResult] = await Promise.allSettled([
  getUser(id),
  getActivity(id),  // this one failing shouldn't break the page
]);

const user = userResult.status === 'fulfilled' ? userResult.value : null;
const activity = activityResult.status === 'fulfilled' ? activityResult.value : [];

The profile still renders if activity fails to load. Use Promise.allSettled for supplementary data, Promise.all for essential data where partial failure means the page can't render meaningfully.

Suspense as a Parallelism Tool

Beyond the loading skeleton use-case from F-4, Suspense has a second role: it allows independent subtrees to fetch in parallel without blocking each other, regardless of how deep the component tree goes.

tsx
// app/dashboard/page.tsx

import { Suspense } from 'react';
import StatsPanel from '@/components/StatsPanel';
import RecentOrders from '@/components/RecentOrders';
import ActivityFeed from '@/components/ActivityFeed';

export default async function DashboardPage({ params }) {
  const { userId } = await params;

  return (
    <div className="grid grid-cols-3 gap-4">
      {/* These three components fetch independently and in parallel */}
      <Suspense fallback={<StatsSkeleton />}>
        <StatsPanel userId={userId} />
      </Suspense>
      <Suspense fallback={<OrdersSkeleton />}>
        <RecentOrders userId={userId} />
      </Suspense>
      <Suspense fallback={<ActivitySkeleton />}>
        <ActivityFeed userId={userId} />
      </Suspense>
    </div>
  );
}

Each Suspense boundary is independent — StatsPanel fetching doesn't block ActivityFeed from starting. The fastest one renders first; slow ones stream in later. The page never waits for the slowest query before showing anything.

Compare this to a single page-level await for all three data sources: the page would be blank until the slowest one resolves.

The mental model: each <Suspense> boundary is its own independent loading state. Design your component tree so slow data is isolated in its own boundaries, not mixed with fast data in the same await.

unstable_cache — Persisting Query Results Across Requests

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

ts
// 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
  }
);

tsx
// 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:

ts
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:

ts
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.

ts
// 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

ts
// 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.

tsx
// ❌ 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} />;
}

tsx
// ✅ 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 P-6 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":

tsx
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:

tsx
// 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.

ts
// 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-6 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-6 extends.