Data Fetching Architecture

Overview

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

Core Principles

• Server components call server functions directly

• Client components use TanStack Query to fetch from API routes

• API routes wrap server functions using apiRouteWrapper

• Mutations from client components call server functions directly

• 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

• Server components: Call server functions directly with await

• Client queries: Use TanStack Query + API routes

• Client mutations: Call server functions directly

• TMDB: Use auto-generated functions, never edit manually

• API routes: Use apiRouteWrapper

• 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)