Frontend Routing (TanStack Router)

Relevant source files

The following files were used as context for generating this wiki page:

• apps/web/src/routeTree.gen.ts
• apps/web/src/router.tsx
• apps/web/src/routes/__root.tsx
• apps/web/src/routes/index.tsx
• apps/web/README.md
• apps/web/src/components/Header.tsx
• apps/web/src/routes/api.demo-names.ts
• apps/web/package.json

The web application utilizes TanStack Router for a modern, type-safe routing solution. It is configured to use a file-based routing system, where the directory structure within apps/web/src/routes dictates the application's URL paths. This approach simplifies route management and leverages code generation to ensure type safety across the application.

The routing is deeply integrated with other TanStack libraries, notably TanStack Query for data fetching, providing a cohesive development experience. The setup includes a root layout for shared UI elements, automatic route tree generation, and developer tools for debugging.

Sources: README.md, apps/web/README.md, apps/web/package.json:20-25

Architecture Overview

The routing architecture is centered around three key concepts: router instantiation, file-based route definitions, and an automatically generated route tree.

1. Router Instantiation: The main router instance is created in apps/web/src/router.tsx. It combines the core TanStack Router with TanStack Query for integrated data fetching capabilities.
2. File-Based Routes: Routes are defined as files within the apps/web/src/routes directory. For example, index.tsx corresponds to the / path. A special file, __root.tsx, defines the global layout for all routes.
3. Route Tree Generation: The file apps/web/src/routeTree.gen.ts is automatically generated by TanStack Router. It reads the file system in src/routes and creates a strongly-typed route tree, which is then imported and used by the router instance.

This diagram illustrates the initialization flow of the router.

Key Components and Files

The routing system is composed of several critical files and directories.

File/Directory	Description
apps/web/src/router.tsx	Initializes the TanStack Router, integrates it with TanStack Query, and exports the createRouter function.
apps/web/src/routes/	The directory containing all file-based route definitions.
apps/web/src/routes/__root.tsx	Defines the root layout component for the entire application, including the HTML shell, header, and the <Outlet /> for nested routes.
apps/web/src/routes/index.tsx	Defines the component for the index route (/).
apps/web/src/routeTree.gen.ts	An auto-generated file that creates the type-safe route tree from the files in the src/routes directory. This file should not be manually edited.
apps/web/src/components/Header.tsx	A UI component that demonstrates navigation using the <Link> component from @tanstack/react-router.

Sources: apps/web/src/router.tsx, apps/web/src/routes/__root.tsx, apps/web/src/routes/index.tsx, apps/web/src/routeTree.gen.ts, apps/web/src/components/Header.tsx

Router Initialization

The router is created in apps/web/src/router.tsx. The createRouter function initializes the router using createTanstackRouter and enhances it with TanStack Query capabilities via routerWithQueryClient.

Key configurations include:

• routeTree: Imports the auto-generated route tree from ./routeTree.gen.ts.
• context: Injects the TanStack Query client into the router's context, making it available to all routes.
• scrollRestoration: Enabled to restore scroll position on navigation.

// apps/web/src/router.tsx:10-22
export function createRouter() {
  const router = routerWithQueryClient(
    createTanstackRouter({
      routeTree,
      context: {
        ...TanstackQuery.getContext(),
      },
      scrollRestoration: true,
      defaultPreloadStaleTime: 0,
    }),
    TanstackQuery.getContext().queryClient,
  );

  return router;
}

A Register interface is declared to provide global type-safety for the router instance throughout the application.

Sources: apps/web/src/router.tsx:1-29

File-Based Routing

Root Layout

The root layout is defined in apps/web/src/routes/__root.tsx. It acts as a shell for all pages.

• It uses createRootRouteWithContext to create the route and define the context type, which includes the QueryClient.
• The component renders the main HTML structure (<html>, <head>, <body>).
• It includes a shared <Header /> component.
• The <Outlet /> component is used to render the content of the active child route.
• It also renders <TanStackRouterDevtools /> for debugging purposes.

The following diagram shows the component structure of the root layout.

Page Routes

Page routes are created by adding files to the src/routes directory. For example, the home page is defined in apps/web/src/routes/index.tsx. The createFileRoute function is used to define the route, which is automatically associated with the / path based on its filename.

// apps/web/src/routes/index.tsx:4-6
export const Route = createFileRoute("/")({
  component: App,
});

Sources: apps/web/src/routes/index.tsx:4-6, apps/web/README.md:34-38

API Routes

The routing system also supports backend API routes that can be defined within the same file-based structure. The file apps/web/src/routes/api.demo-names.ts demonstrates this using createAPIFileRoute. This creates a GET endpoint at /api/demo-names.

// apps/web/src/routes/api.demo-names.ts:3-11
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-11

Route Tree Generation

The file apps/web/src/routeTree.gen.ts is a critical piece of the routing system, although it is never manually edited. It is generated by a TanStack Router plugin and contains the fully typed route hierarchy.

• It imports all route definitions from the src/routes directory.
• It constructs the route tree by nesting child routes under their parents (e.g., IndexRoute is a child of rootRoute).
• It exports TypeScript interfaces like FileRoutesByPath and FileRoutesById that provide strong type-checking for navigation and route-related hooks.
• A ROUTE_MANIFEST is included at the end of the file, which maps route IDs to their file paths.

// apps/web/src/routeTree.gen.ts:60-71
/* ROUTE_MANIFEST_START
{
  "routes": {
    "__root__": {
      "filePath": "__root.tsx",
      "children": [
        "/"
      ]
    },
    "/": {
      "filePath": "index.tsx"
    }
  }
}
ROUTE_MANIFEST_END */

Sources: apps/web/src/routeTree.gen.ts, apps/web/package.json:24

Navigation

Programmatic, single-page application (SPA) navigation is handled by the <Link> component from @tanstack/react-router. This component provides type-safe links to other routes. The Header component provides a practical example of its usage.

// apps/web/src/components/Header.tsx:5-7
<nav className="flex flex-row">
  <div className="px-2 font-bold">
    <Link to="/">Home</Link>
  </div>

This creates a client-side navigation link to the home page without a full page reload.

Sources: apps/web/src/components/Header.tsx:1-34, apps/web/README.md:41-47

Conclusion

The frontend routing in this project is built on a robust and type-safe foundation provided by TanStack Router. Its file-based routing convention, automatic route tree generation, and seamless integration with TanStack Query create an efficient and maintainable system. The use of a root layout ensures a consistent UI, while the <Link> component enables smooth SPA navigation. This architecture is well-suited for modern, scalable React applications.

Sources: README.md, apps/web/README.md