Data Fetching

// A pure mapping layer: the rest of the app only ever sees `Book`, whichever backend answers.
import type { Book } from "@/lib/types";

type DrfPage<T> = { count: number; next: string | null; previous: string | null; results: T[] };
type DjangoBook = { id: number; title: string; author_id: number; price_cents: number };

export function fromDjangoPage(page: DrfPage<DjangoBook>): Book[] {
  return page.results.map((b) => ({
    id: b.id,
    title: b.title,
    authorId: b.author_id,
    priceCents: b.price_cents,
  }));
}

import "server-only";
import { cookies } from "next/headers";

// Forward the caller's credential to the API from the server; the browser never sees the upstream URL.
export async function getMe() {
  const token = (await cookies()).get("access_token")?.value;
  if (!token) return null;
  const res = await fetch(`${process.env.BOOKSHELF_API_URL ?? "http://localhost:3611"}/me`, {
    headers: { Authorization: `Bearer ${token}` },
    signal: AbortSignal.timeout(3000), // never wait forever for a slow upstream
  });
  if (res.status === 401) return null;
  if (!res.ok) throw new Error(`Bookshelf API /me answered ${res.status}`);
  return (await res.json()) as { name: string };
}

import { getMe } from "@/lib/me";

export default async function Page() {
  const me = await getMe(); // cookies() makes this route dynamic: rendered per request
  return <p>{me ? `Hello, ${me.name}` : "Signed out"}</p>;
}

curl -s localhost:3601/df/me                                      # Signed out
curl -s -H "Cookie: access_token=demo-token" localhost:3601/df/me # Hello, Reader
curl -s -H "Cookie: access_token=wrong" localhost:3601/df/me      # Signed out

import { connection } from "next/server";
import { getBooks } from "@/lib/bookshelf";

export default async function BooksPage({ searchParams }: PageProps<"/df/books">) {
  await connection(); // render per request; fetch alone is not cached but would be prerendered
  const { q } = await searchParams;
  const books = await getBooks(typeof q === "string" ? q : "");
  return (
    <ul>
      {books.map((b) => (
        <li key={b.id}>{b.title} ({(b.priceCents / 100).toFixed(2)})</li>
      ))}
    </ul>
  );
}

curl -s "localhost:3601/df/books?q=sol"   # <ul><li>Solaris (7.99)</li></ul>

import "server-only";
import { cache } from "react";

// Stand-in for an ORM or database client (Drizzle, Prisma, pg ...).
const rows = [
  { id: 1, title: "Dune", priceCents: 999 },
  { id: 2, title: "Neuromancer", priceCents: 899 },
];

// cache() deduplicates calls with the same arguments during ONE render pass (one request).
export const getBookRow = cache(async (id: number) => {
  console.log(`DB query for book ${id}`); // visible once per request, not once per caller
  return rows.find((r) => r.id === id) ?? null;
});

Error: 'server-only' cannot be imported from a Client Component module
Import traces:
  Client Component Browser:
    ./lib/bookshelf.ts [Client Component Browser]
    ./app/df/bad/page.tsx [Client Component Browser]

import { getReviews } from "@/lib/bookshelf";

export default async function Page() {
  const reviews = await getReviews(1); // uncached fetch outside <Suspense>
  return <p>{reviews.length}</p>;
}

Error: Route "/df/cc-bad": Next.js encountered uncached or runtime data during prerendering.

`fetch(...)`, `cookies()`, `headers()`, `params`, `searchParams`, or `connection()` accessed outside of `<Suspense>`
prevents the route from being prerendered, blocking the page load and leading to a slower user experience.

Ways to fix this:
  - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access
  - [cache] For uncached data (`fetch`, database calls): cache the access with `"use cache"`
  - [block] Set `export const instant = false` to allow a blocking route

import { Suspense } from "react";
import { cacheLife } from "next/cache";
import { getBooks, getReviews } from "@/lib/bookshelf";

// Cached: becomes part of the prerendered static shell and is revalidated in the background.
async function Catalogue() {
  "use cache";
  cacheLife("minutes");
  const books = await getBooks();
  return <ul>{books.map((b) => <li key={b.id}>{b.title}</li>)}</ul>;
}

// Not cached: an uncached fetch is "dynamic" under Cache Components and must be inside <Suspense>.
async function LatestReviews() {
  const reviews = await getReviews(1);
  return <p>{reviews.length} review(s) right now</p>;
}

export default function Page() {
  return (
    <main>
      <h1>Bookshelf</h1>
      <Catalogue />
      <Suspense fallback={<p>Loading reviews...</p>}>
        <LatestReviews />
      </Suspense>
    </main>
  );
}

Route (app)      Revalidate  Expire
├ ƒ /api/books
└ ◐ /df/cc               1m      1h

◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

import { connection } from "next/server";
import { getAuthor, getBook, getReviews } from "@/lib/bookshelf";

export default async function Page({ params }: PageProps<"/df/waterfall/[id]">) {
  await connection();
  const { id } = await params;
  const book = await getBook(Number(id)); // 300 ms
  const author = await getAuthor(book.authorId); // +300 ms: genuinely depends on book
  const reviews = await getReviews(book.id); // +300 ms: does NOT depend on author, an avoidable wait
  return <h1>{book.title} by {author.name} ({reviews.length} reviews)</h1>;
}

import { connection } from "next/server";
import { getAuthor, getBook, getReviews } from "@/lib/bookshelf";

export default async function Page({ params }: PageProps<"/df/parallel/[id]">) {
  await connection();
  const { id } = await params;
  // Start every request that does not depend on another one, then await late.
  const bookPromise = getBook(Number(id));
  const reviewsPromise = getReviews(Number(id));
  const book = await bookPromise;
  const author = await getAuthor(book.authorId); // runs while reviews are already in flight
  const reviews = await reviewsPromise;
  return <h1>{book.title} by {author.name} ({reviews.length} reviews)</h1>;
}

import { Suspense } from "react";
import { connection } from "next/server";
import { getAuthor, getBook, getReviews } from "@/lib/bookshelf";

export default async function Page({ params }: PageProps<"/df/streamed/[id]">) {
  await connection();
  const { id } = await params;
  const book = await getBook(Number(id)); // the only thing the shell waits for
  return (
    <main>
      <h1>{book.title}</h1>
      <Suspense fallback={<p>Loading author...</p>}>
        <Author authorId={book.authorId} />
      </Suspense>
      <Suspense fallback={<p>Loading reviews...</p>}>
        <Reviews bookId={book.id} />
      </Suspense>
    </main>
  );
}

async function Author({ authorId }: { authorId: number }) {
  const author = await getAuthor(authorId);
  return <p>by {author.name}</p>;
}

async function Reviews({ bookId }: { bookId: number }) {
  const reviews = await getReviews(bookId);
  return <p>{reviews.length} review(s)</p>;
}

"use client";
import { useState } from "react";
import useSWR from "swr";
import type { Book } from "@/lib/types";

async function fetcher(url: string): Promise<Book[]> {
  const res = await fetch(url);
  if (!res.ok) throw new Error("Failed to fetch books");
  return res.json();
}

export function BookSearch() {
  const [q, setQ] = useState("");
  // A null key pauses the request until the user has typed something.
  const { data = [], error, isLoading } = useSWR(
    q ? `/api/books?q=${encodeURIComponent(q)}` : null,
    fetcher,
  );
  return (
    <div>
      <input value={q} onChange={(e) => setQ(e.target.value)} placeholder="Search books" />
      {error && <p>Failed to load books.</p>}
      {isLoading && <p>Loading...</p>}
      <ul>{data.map((b) => <li key={b.id}>{b.title}</li>)}</ul>
    </div>
  );
}

// app/df/swr/books-key.ts  (no "use client": both sides import it)
export const booksKey = (q: string) => `/api/books?q=${encodeURIComponent(q)}`;

// app/df/swr/page.tsx
import { Suspense } from "react";
import { SWRConfig } from "swr";
import { connection } from "next/server";
import { getBooks } from "@/lib/bookshelf";
import { BookList } from "./book-list";
import { booksKey } from "./books-key";

export default async function Page() {
  await connection();
  return (
    <main>
      <Suspense fallback={<p>Loading books...</p>}>
        <SWRConfig value={{ fallback: { [booksKey("")]: getBooks("") } }}>
          <BookList q="" />
        </SWRConfig>
      </Suspense>
    </main>
  );
}

// app/df/swr/book-list.tsx
"use client";
import useSWR from "swr";
import type { Book } from "@/lib/types";
import { booksKey } from "./books-key";

async function fetcher(url: string): Promise<Book[]> {
  const res = await fetch(url);
  if (!res.ok) throw new Error("Failed to fetch books");
  return res.json();
}

// Same key as the server-provided fallback, so the first render needs no browser request.
export function BookList({ q }: { q: string }) {
  const { data } = useSWR(booksKey(q), fetcher, { suspense: true });
  return <ul>{data.map((b) => <li key={b.id}>{b.title}</li>)}</ul>;
}

HTTP: the streamed HTML contains <li>Dune</li><li>Neuromancer</li><li>Solaris</li> inside the Suspense hole
Browser: the page renders the three books, then SWR revalidates once: GET /api/books?q=

"use client";
import type { ReactNode } from "react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

let browserQueryClient: QueryClient | undefined;

function getQueryClient() {
  // A fresh client per server render (requests must not share a cache); one client in the browser.
  if (typeof window === "undefined") return new QueryClient();
  browserQueryClient ??= new QueryClient();
  return browserQueryClient;
}

export function Providers({ children }: { children: ReactNode }) {
  return <QueryClientProvider client={getQueryClient()}>{children}</QueryClientProvider>;
}

// app/df/query/layout.tsx
import { Providers } from "./providers";

export default function Layout({ children }: LayoutProps<"/df/query">) {
  return <Providers>{children}</Providers>;
}

// app/df/query/books-cache.ts
import { queryOptions } from "@tanstack/react-query";
import type { Book } from "@/lib/types";

export const booksCache = {
  key: (q: string) => ["books", q] as const,
  options: (q: string) =>
    queryOptions({
      queryKey: booksCache.key(q),
      queryFn: async (): Promise<Book[]> => {
        const res = await fetch(`/api/books?q=${encodeURIComponent(q)}`);
        if (!res.ok) throw new Error("Failed to fetch books");
        return res.json();
      },
      staleTime: 30_000, // keep server-provided data fresh so the client does not refetch at once
    }),
};

// app/df/query/page.tsx
import { Suspense } from "react";
import { connection } from "next/server";
import { defaultShouldDehydrateQuery, dehydrate, HydrationBoundary, QueryClient } from "@tanstack/react-query";
import { getBooks } from "@/lib/bookshelf";
import { booksCache } from "./books-cache";
import { BookList } from "./book-list";

export default async function Page() {
  await connection();
  return (
    <Suspense fallback={<p>Loading books...</p>}>
      <BooksData />
    </Suspense>
  );
}

function BooksData() {
  const queryClient = new QueryClient();
  // Not awaited, so rendering is not blocked; the pending query is streamed.
  void queryClient.prefetchQuery({ ...booksCache.options(""), queryFn: () => getBooks("") });
  return (
    <HydrationBoundary
      state={dehydrate(queryClient, {
        shouldDehydrateQuery: (query) =>
          defaultShouldDehydrateQuery(query) || query.state.status === "pending",
      })}
    >
      <BookList q="" />
    </HydrationBoundary>
  );
}

// app/df/query/book-list.tsx
"use client";
import { useSuspenseQuery } from "@tanstack/react-query";
import { booksCache } from "./books-cache";

export function BookList({ q }: { q: string }) {
  const { data } = useSuspenseQuery(booksCache.options(q));
  return <ul>{data.map((b) => <li key={b.id}>{b.title}</li>)}</ul>;
}

"use client";
import { useEffect, useState } from "react";
import type { Book } from "@/lib/types";

export function BookEffect({ q }: { q: string }) {
  const [books, setBooks] = useState<Book[] | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const controller = new AbortController();
    // The effect callback itself is not async: it returns the cleanup function.
    async function load() {
      try {
        const res = await fetch(`/api/books?q=${encodeURIComponent(q)}`, { signal: controller.signal });
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        setBooks(await res.json());
      } catch (e) {
        if (e instanceof DOMException && e.name === "AbortError") return; // superseded or unmounted
        setError(e instanceof Error ? e.message : "unknown error");
      }
    }
    load();
    return () => controller.abort();
  }, [q]);

  if (error) return <p>Error: {error}</p>;
  if (!books) return <p>Loading...</p>;
  return <ul>{books.map((b) => <li key={b.id}>{b.title}</li>)}</ul>;
}

// lib/bookshelf-graphql.ts
import "server-only";

export async function graphql<T>(query: string, variables: Record<string, unknown> = {}): Promise<T> {
  const res = await fetch(process.env.BOOKSHELF_GRAPHQL_URL ?? "http://localhost:3611/graphql", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query, variables }),
  });
  if (!res.ok) throw new Error(`GraphQL endpoint answered ${res.status}`);
  const body = (await res.json()) as { data?: T; errors?: { message: string }[] };
  if (body.errors?.length) throw new Error(body.errors[0].message); // GraphQL errors come with HTTP 200
  return body.data as T;
}

// lib/apollo.ts
import { HttpLink } from "@apollo/client";
import { registerApolloClient, ApolloClient, InMemoryCache } from "@apollo/client-integration-nextjs";

// One client per request for every Server Component. Absolute URL: relative URLs cannot be used on the server.
export const { getClient, query, PreloadQuery } = registerApolloClient(() => {
  return new ApolloClient({
    cache: new InMemoryCache(),
    link: new HttpLink({ uri: process.env.BOOKSHELF_GRAPHQL_URL ?? "http://localhost:3611/graphql" }),
  });
});

// lib/queries.ts
import { gql } from "@apollo/client";

export const BOOKS = gql`
  query Books {
    books {
      id
      title
      author {
        id
        name
      }
    }
  }
`;

// app/df/apollo/apollo-wrapper.tsx
"use client";
import { HttpLink } from "@apollo/client";
import { ApolloNextAppProvider, ApolloClient, InMemoryCache } from "@apollo/client-integration-nextjs";

function makeClient() {
  // Browser requests go to the BFF or to a CORS-enabled API; SSR needs an absolute URL.
  const link = new HttpLink({ uri: process.env.NEXT_PUBLIC_GRAPHQL_URL ?? "http://localhost:3611/graphql" });
  return new ApolloClient({ cache: new InMemoryCache(), link });
}

export function ApolloWrapper({ children }: React.PropsWithChildren) {
  return <ApolloNextAppProvider makeClient={makeClient}>{children}</ApolloNextAppProvider>;
}

// app/df/apollo/layout.tsx
import { ApolloWrapper } from "./apollo-wrapper";

export default function Layout({ children }: LayoutProps<"/df/apollo">) {
  return <ApolloWrapper>{children}</ApolloWrapper>;
}

// app/df/apollo/client-books.tsx
"use client";
import { useSuspenseQuery } from "@apollo/client/react";
import { BOOKS } from "@/lib/queries";

type Data = { books: { id: string; title: string; author: { id: string; name: string } }[] };

export function ClientBooks() {
  const { data } = useSuspenseQuery<Data>(BOOKS);
  return <ul>{data.books.map((b) => <li key={b.id}>{b.title} - {b.author.name}</li>)}</ul>;
}

// app/df/apollo/page.tsx
import { Suspense } from "react";
import { connection } from "next/server";
import { PreloadQuery, query } from "@/lib/apollo";
import { BOOKS } from "@/lib/queries";
import { ClientBooks } from "./client-books";

export default async function Page() {
  await connection();
  const { data } = await query<{ books: { id: string; title: string }[] }>({ query: BOOKS });
  return (
    <main>
      <p>Server Component sees {data!.books.length} books</p>
      {/* Separate client instance: the data is seeded into the browser cache, not shared with RSC */}
      <PreloadQuery query={BOOKS}>
        <Suspense fallback={<p>Loading...</p>}>
          <ClientBooks />
        </Suspense>
      </PreloadQuery>
    </main>
  );
}

Server Component sees 3 books
Dune - Frank Herbert
Neuromancer - William Gibson
Solaris - Stanislaw Lem
Browser requests to the API or to /api: none (the client list was streamed from the server's PreloadQuery)