Frontend API Client

The web application includes a server-side API handling system, rather than a traditional client-side data fetching library. This system is built using TanStack Start and enables the creation of file-based API routes that are co-located with the frontend code. These routes are processed on the server, providing a mechanism for server-side rendering (SSR) data fetching and handling simple API logic directly within the frontend application package.

This internal API system is distinct from the main, contract-based Hono/oRPC backend found in the apps/api package. The overall project architecture separates the primary business logic into the backend API, while the frontend's API routes serve purposes specific to the web client's immediate needs. The connection between the frontend and the main backend is noted as a work in progress.

Sources: README.md, apps/web/src/api.ts, apps/web/src/routes/api.demo-names.ts

Architecture and Request Flow

The frontend API system leverages TanStack Start's file-based routing capabilities, which are powered by Vinxi. When a request is made to the web server, Vinxi intercepts it and, based on the URL path, directs it to either a React component for rendering or a specific API route handler. The file apps/web/src/api.ts serves as the central entry point for all API requests handled by this system.

Sources: apps/web/package.json:28, apps/web/src/api.ts:1-6

The following diagram illustrates the request handling flow for an API route within the web application.

This diagram shows how an incoming API request is processed by the createStartAPIHandler which then uses the file-based routing to find and execute the correct handler.
Sources: apps/web/src/api.ts:6, apps/web/src/routes/api.demo-names.ts:3-11

API Route Handling

The core of the frontend's API handling is configured in apps/web/src/api.ts. This file exports a default handler created by createStartAPIHandler from @tanstack/react-start/api. This function is responsible for orchestrating the file-based API routing. It uses defaultAPIFileRouteHandler to discover and execute the appropriate API route based on the file system structure under src/routes.

// apps/web/src/api.ts
import {
  createStartAPIHandler,
  defaultAPIFileRouteHandler,
} from "@tanstack/react-start/api";

export default createStartAPIHandler(defaultAPIFileRouteHandler);

Sources: apps/web/src/api.ts:1-6

Defining API Routes

API routes are defined as files within the apps/web/src/routes/ directory. The file path directly maps to the API endpoint URL. For example, the file api.demo-names.ts creates an endpoint at /api/demo-names.

The createAPIFileRoute function from @tanstack/react-start/api is used to define the route and its handlers for different HTTP methods, such as GET.

Example: /api/demo-names

This route provides a static list of names.

// apps/web/src/routes/api.demo-names.ts
import { createAPIFileRoute } from "@tanstack/react-start/api";

export const APIRoute = createAPIFileRoute("/api/demo-names")({
  GET: async ({ request }) => {
    return new Response(JSON.stringify(["Alice", "Bob", "Charlie"]), {
      headers: {
        "Content-Type": "application/json",
      },
    });
  },
});

Sources: apps/web/src/routes/api.demo-names.ts:1-12

The following table summarizes the API routes defined within the web application.

Key Dependencies

The functionality of the frontend API client is supported by several key packages listed in the web application's package.json.

Sources: apps/web/package.json:28,31,40

Data Fetching on the Client

While the web app can serve its own API routes, it primarily uses TanStack Query (@tanstack/react-query) for client-side data fetching and state management. The web app's README.md details how to use the useQuery hook to fetch data from an API endpoint, which could be one of the internal file-based routes or the main external Hono API.

The following sequence diagram shows a typical client-side data fetching flow using useQuery.

This diagram illustrates how a React component uses TanStack Query to initiate a data fetch, which in turn uses the browser's Fetch API to call an endpoint and return the data to the component.
Sources: apps/web/README.md:121-140, apps/web/src/routes/api.demo-names.ts