Next.js Data Fetching Skill - A Claude Code skill recipe for mastering Next.js data fetching, streaming, and caching

---
name: nextjs-data-fetching
description: "Mastering data fetching with Next.js 15+, streaming, partial prerendering, and caching strategies. Use when asked to: data fetching, caching strategy, streaming, revalidation, server actions, fetch patterns, waterfall prevention, PPR."
allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(npm:*), Bash(npx:*), Agent"
---
 
# Next.js Data Fetching
 
You are a Next.js data fetching expert. Provide authoritative guidance on fetching, caching, revalidation, streaming, and Server Actions.
 
## Fetching Strategy Decision Matrix
 
| Scenario | Strategy | Where |
|----------|----------|-------|
| Static page content | fetch at build time | Server Component |
| User-specific data | fetch at request time | Server Component with cookies/headers |
| Form submission | Server Action | "use server" function |
| Real-time updates | Client-side fetch (SWR or React Query) | Client Component |
| List + detail prefetch | Parallel fetches with Promise.all | Server Component |
| Infinite scroll | Client-side fetch with pagination | Client Component |
| Search with URL params | searchParams in page | Server Component |
| Optimistic mutation | useOptimistic + Server Action | Client Component |
 
## Server Component Fetching
 
### Basic Pattern
```tsx
// app/posts/page.tsx - Server Component (default)
async function getPosts() \{
  const res = await fetch("https://api.example.com/posts", \{
    next: \{ revalidate: 3600 \}, // ISR: revalidate every hour
  \});
  if (!res.ok) throw new Error("Failed to fetch posts");
  return res.json() as Promise<Post[]>;
\}
 
export default async function PostsPage() \{
  const posts = await getPosts();
  return (
    <ul>
      \{posts.map((post) => (
        <li key=\{post.id\}>\{post.title\}</li>
      ))\}
    </ul>
  );
\}

// BAD: Sequential waterfall
async function Page() \{
  const user = await getUser();    // 200ms
  const posts = await getPosts();  // 300ms
  // Total: 500ms
 
// GOOD: Parallel fetching
async function Page() \{
  const [user, posts] = await Promise.all([
    getUser(),   // 200ms
    getPosts(),  // 300ms
  ]);
  // Total: 300ms (max of both)

export default async function SearchPage(\{
  searchParams,
\}: \{
  searchParams: Promise<\{ q?: string; page?: string \}>;
\}) \{
  const \{ q, page \} = await searchParams;
  const results = await search(q ?? "", Number(page ?? "1"));
  return <SearchResults results=\{results\} />;
\}

// Opt-in to caching
fetch(url, \{ cache: "force-cache" \});
 
// Cache with time-based revalidation
fetch(url, \{ next: \{ revalidate: 3600 \} \});
 
// No cache (default in Next.js 15)
fetch(url, \{ cache: "no-store" \});
// or simply: fetch(url) - no-store is the default

// Time-based revalidation
fetch(url, \{ next: \{ revalidate: 60 \} \});
 
// On-demand revalidation by path
import \{ revalidatePath \} from "next/cache";
revalidatePath("/posts");
 
// On-demand revalidation by tag
import \{ revalidateTag \} from "next/cache";
// When fetching:
fetch(url, \{ next: \{ tags: ["posts"] \} \});
// When mutating:
revalidateTag("posts");

import \{ unstable_cache \} from "next/cache";
 
const getCachedUser = unstable_cache(
  async (id: string) => db.user.findUnique(\{ where: \{ id \} \}),
  ["user"],       // cache key parts
  \{ revalidate: 3600, tags: ["user"] \}
);

import \{ Suspense \} from "react";
 
export default function DashboardPage() \{
  return (
    <div>
      <h1>Dashboard</h1>
      \{/* This renders immediately */\}
      <StaticHeader />
 
      \{/* These stream in independently */\}
      <Suspense fallback=\{<ChartSkeleton />\}>
        <RevenueChart />
      </Suspense>
      <Suspense fallback=\{<TableSkeleton />\}>
        <RecentOrders />
      </Suspense>
    </div>
  );
\}
 
// Each async component streams when ready
async function RevenueChart() \{
  const data = await getRevenue(); // slow query
  return <Chart data=\{data\} />;
\}
 
async function RecentOrders() \{
  const orders = await getOrders(); // another slow query
  return <OrdersTable orders=\{orders\} />;
\}

// next.config.ts
const config = \{
  experimental: \{
    ppr: true,
  \},
\};
 
// app/product/[id]/page.tsx
import \{ Suspense \} from "react";
 
export default async function ProductPage(\{
  params,
\}: \{
  params: Promise<\{ id: string \}>;
\}) \{
  const \{ id \} = await params;
  const product = await getProduct(id); // static (cached)
 
  return (
    <div>
      \{/* Static shell - prerendered */\}
      <h1>\{product.name\}</h1>
      <p>\{product.description\}</p>
 
      \{/* Dynamic holes - streamed at request time */\}
      <Suspense fallback=\{<PriceSkeleton />\}>
        <DynamicPrice productId=\{id\} />
      </Suspense>
      <Suspense fallback=\{<ReviewsSkeleton />\}>
        <DynamicReviews productId=\{id\} />
      </Suspense>
    </div>
  );
\}

// actions.ts
"use server";
 
import \{ revalidatePath \} from "next/cache";
import \{ redirect \} from "next/navigation";
 
export async function createPost(formData: FormData) \{
  const title = formData.get("title") as string;
  const body = formData.get("body") as string;
 
  // Always validate server-side
  if (!title || title.length < 3) \{
    return \{ error: "Title must be at least 3 characters" \};
  \}
 
  await db.post.create(\{ data: \{ title, body \} \});
  revalidatePath("/posts");
  redirect("/posts");
\}

// lib/data.ts
export function preloadUser(id: string) \{
  void getUser(id); // fire fetch, discard promise (request memoization caches it)
\}
 
// app/user/[id]/page.tsx
import \{ preloadUser \} from "@/lib/data";
 
export default async function UserPage(\{
  params,
\}: \{
  params: Promise<\{ id: string \}>;
\}) \{
  const \{ id \} = await params;
  preloadUser(id); // start fetching immediately
  // ... other work ...
  const user = await getUser(id); // hits memoization cache
  return <UserProfile user=\{user\} />;
\}

mkdir -p .claude/skills/nextjs-data-fetching
# Paste the Recipe content into .claude/skills/nextjs-data-fetching/SKILL.md