data-fetching

name	data-fetching
description	Data fetching patterns for server/client components using fetch API, TanStack Query, useSuspenseQuery, apiRouteWrapper, and apiRequestWrapper. Use when implementing data loading, API calls, server functions, queries, mutations, API routes, or when the user mentions TanStack Query, useSuspenseQuery, apiRouteWrapper, apiRequestWrapper, tmdb-server-functions, or data fetching.

Data Fetching Architecture

Overview

This project uses a structured data fetching pattern that differs between server and client components.

Core Principles

1. Server components call server functions directly
2. Client components use TanStack Query to fetch from API routes
3. API routes wrap server functions using apiRouteWrapper
4. Mutations from client components call server functions directly
5. TMDB API uses auto-generated server functions from tmdb-server-functions.ts

Server Components

Server components can directly await server functions.

import { discoverMovies } from "@/utils/tmdb-server-functions";

function serverFunction() {
  return fetch(URL, headers);
}

function ServerComponent() {
  const movies = await discoverMovies({
    page: 1,
    with_genres: "28",
  });

  const myResults = await serverFunction();

  return <div>...</div>;
}

Use await directly in server components. Call TMDB server functions from @/utils/tmdb-server-functions.

Client Components + API Routes

Client components use TanStack Query to call API routes, which wrap server functions.

Step 1: Create API Route

API routes use apiRouteWrapper to wrap server functions:

// src/app/api/tmdb/discover-movies/route.ts
import { apiRouteWrapper } from "@/utils/api-route-wrapper";
import { discoverMovies } from "@/utils/tmdb-server-functions";

export const GET = apiRouteWrapper(discoverMovies);

For custom server functions:

// src/app/api/some-api-route/route.ts
import { apiRouteWrapper } from "@/utils/api-route-wrapper";
import { myServerFunction } from "@/some-server-function";

export const GET = apiRouteWrapper(async (params) => {
  return myServerFunction(params);
});

Step 2: Call from Client Component

Use TanStack Query with apiRequestWrapper:

"use client";
import { useSuspenseQuery } from "@tanstack/react-query";
import { apiRequestWrapper } from "@/utils/api-request-wrapper";

function ClientComponent() {
  const { data: movies } = useSuspenseQuery({
    queryKey: [{ scope: "movies", page: 1, with_genres: "28" }],
    queryFn: () =>
      apiRequestWrapper("/api/tmdb/movie-list", {
        page: 1,
        with_genres: "28",
      }),
  });

  const { data: results } = useSuspenseQuery({
    queryKey: [{ scope: "someApiRoute" }],
    queryFn: () =>
      apiRequestWrapper("/api/some-api-route", {
        foo: "bar",
      }),
  });

  return <div>...</div>;
}

Mutations from Client Components

For mutations, client components call server functions directly (no API route needed).

"use client";
import { useMutation } from "@tanstack/react-query";
import { updateMovie } from "@/server-functions/movies";

function ClientComponent() {
  const mutation = useMutation({
    mutationFn: updateMovie,
  });

  const handleUpdate = () => {
    mutation.mutate({ id: 1, title: "New Title" });
  };

  return <button onClick={handleUpdate}>Update</button>;
}

TMDB API Integration

TMDB server functions are auto-generated from src/_generated/tmdb-server-functions.ts.

Important: These are auto-generated - DO NOT edit manually. Use pnpm codegen:tmdb to regenerate.

// Import TMDB functions
import {
  discoverMovies,
  getMovieDetails,
  searchMovies,
} from "@/utils/tmdb-server-functions";

// Server component usage
async function MovieList() {
  const movies = await discoverMovies({
    page: 1,
    with_genres: "28",
  });

  return <div>...</div>;
}

// API route for client components
// src/app/api/tmdb/discover-movies/route.ts
export const GET = apiRouteWrapper(discoverMovies);

Pattern Summary

Server Component Data Flow

Server Component → Server Function → External API/Database

Client Component Data Flow (Queries)

Client Component → TanStack Query → API Route → Server Function → External API/Database

Client Component Data Flow (Mutations)

Client Component → TanStack Query Mutation → Server Function → External API/Database

Best Practices

1. Server components: Call server functions directly with await
2. Client queries: Use TanStack Query + API routes
3. Client mutations: Call server functions directly
4. TMDB: Use auto-generated functions, never edit manually
5. API routes: Use apiRouteWrapper
6. Client fetching: Use apiRequestWrapper

Common Mistakes

❌ Calling API routes from server components (use server functions directly) ❌ Using fetch directly in client components (use TanStack Query) ❌ Editing tmdb-server-functions.ts manually (regenerate with pnpm codegen:tmdb) ❌ Creating API routes for mutations (call server functions directly)