TanStack Router: Type-Safe Routing in React

1. The Routing Problem in TypeScript React Apps

The fundamental problem with traditional React Router solutions and TypeScript lies in the untyped nature of the URL. A link to /products/42/edit is a string. TypeScript does not know whether the route exists, whether 42 is in the right param position, or whether a required search param is missing. The error surfaces at runtime, often in production, when a user clicks a link that leads to a route that does not exist. TanStack Router changes this fundamentally: routes are typed objects, and the TypeScript type system knows every param, every search param and every nested route.

Another common problem is the unstructured handling of search params. In React Router v6, search params are read with useSearchParams(), which returns a URLSearchParams object, without types, without validation, without default values. TanStack Router treats search params as a first-class citizen: every route defines its search param schema with a validator (Zod, Valibot or a custom function), and every read and write operation on search params is fully typed. Search params become a reactive, type-safe part of the route state.

The third pain point is the lack of built-in loaders in React Router without a framework. Data fetches that should happen before a route renders require either loader functions from a framework wrapper or complex Suspense setups. TanStack Router has loaders built in that run in parallel to parent routes and hand their data to the route component in a fully typed form.

2. Core Principle: Routes as Typed Objects

The design principle behind TanStack Router is consistent: every route is defined with createRoute() or createFileRoute() as a typed object. These objects are assembled into a routeTree and passed to a createRouter() call. The type of the router and its routeTree flows through the entire system: Link, navigate(), useParams() and useSearch() are all derived from the router type and checked by TypeScript.

The root route (createRootRoute()) contains the shell of the application with <Outlet /> as a placeholder for the active child route. Nested routes (createRoute({ getParentRoute: () => rootRoute })) inherit the context of the parent route. Layouts arise from intermediate routes that themselves render only an <Outlet />. This pattern mirrors the nested routing of React Router, but is type-safe and does not rely on string-based route definitions.

// router.tsx: typed route tree with TanStack Router
import { createRouter, createRoute, createRootRoute } from "@tanstack/react-router";
import { TanStackRouterDevtools } from "@tanstack/router-devtools";
import { RootLayout } from "./layouts/RootLayout";
import { ProductsPage } from "./pages/ProductsPage";
import { ProductDetailPage } from "./pages/ProductDetailPage";

// Root route: application shell
const rootRoute = createRootRoute({
  component: () => (
    <>
      <RootLayout />
      <TanStackRouterDevtools />
    </>
  ),
});

// /products: list route
const productsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: "/products",
  component: ProductsPage,
});

// /products/$productId: detail route with typed param
const productDetailRoute = createRoute({
  getParentRoute: () => productsRoute,
  path: "$productId",
  component: ProductDetailPage,
});

// Compose the route tree
const routeTree = rootRoute.addChildren([
  productsRoute.addChildren([productDetailRoute]),
]);

// Router instance: the type flows through the entire app
export const router = createRouter({ routeTree });

// Augment TanStack Router's module with our router type
declare module "@tanstack/react-router" {
  interface Register {
    router: typeof router;
  }
}

3. File-Based Routing with the Vite Plugin

File-based routing in TanStack Router works through the @tanstack/router-plugin/vite plugin, which operates similarly to Next.js or Remix: files in a configured directory (src/routes/) automatically define routes. The file name determines the path: products.tsx maps to /products, products.$productId.tsx maps to /products/$productId, and products_.$productId.edit.tsx maps to /products/$productId/edit without layout nesting. The plugin automatically generates the routeTree.gen.ts file, which contains every route type.

In every route file, createFileRoute('/products/$productId') appears with the correct path. The path string is only needed for type safety. The plugin checks that the file name and the path string match and raises a compile error if they do not. Layouts arise from __layout.tsx files, which automatically act as parent routes for every file in the same directory. This pattern significantly reduces manual route management and keeps the application structure consistent with the file system structure.

4. Route Params: Reading the URL Type-Safely

The most common runtime error in traditional React applications: useParams() returns a Params object whose values are all string | undefined. Every use requires defensive checks. In TanStack Router, thanks to the global router type, useParams() knows exactly which params exist on which route and what types they have. On the productDetailRoute, useParams({ from: '/products/$productId' }) returns an object in which productId is guaranteed to be string, no undefined, no manual guard.

Param validation and transformation happen via the parseParams option in the route definition. There, the raw string param can be transformed into a numeric value: parseParams: (raw) => ({ productId: Number(raw.productId) }). After this transformation, useParams() returns { productId: number }, fully typed. If the param is not a valid number, the transformation function can throw an error, which TanStack Router forwards to the route's errorComponent.

// routes/products.$productId.tsx: typed params and loader
import { createFileRoute } from "@tanstack/react-router";
import { z } from "zod";

// Zod schema for params validation and type inference
const paramsSchema = z.object({
  productId: z.string().regex(/^\d+$/, "Must be a numeric ID").transform(Number),
});

export const Route = createFileRoute("/products/$productId")({
  // Validate and transform raw URL params
  parseParams: (rawParams) => paramsSchema.parse(rawParams),

  // Loader runs before component render: params are fully typed here
  loader: async ({ params }) => {
    // params.productId is number here, not string
    const res = await fetch(`/api/products/${params.productId}`);
    if (!res.ok) throw new Error(`Product ${params.productId} not found`);
    return res.json() as Promise<Product>;
  },

  component: ProductDetailPage,
  errorComponent: ({ error }) => <ErrorBanner message={error.message} />,
  pendingComponent: () => <ProductDetailSkeleton />,
});

function ProductDetailPage() {
  // All types inferred: no casting, no undefined checks
  const { productId } = Route.useParams();       // number
  const product = Route.useLoaderData();          // Product
  const navigate = Route.useNavigate();

  return (
    <div>
      <h1>{product.name}</h1>
      <button onClick={() => navigate({ to: "/products" })}>
        Back to list
      </button>
    </div>
  );
}

5. Search Params: Structured URL State

Search params in TanStack Router are far more than a URLSearchParams wrapper. Every route defines its search param schema with a validation function that describes default values, types and optional fields. The schema can be Zod, Valibot or a simple transformation function. When a user navigates to a route and certain search params are missing, TanStack Router automatically applies the default values defined in the schema. This eliminates the defensive programming that would otherwise be unavoidable when parsing URLSearchParams.

Updating search params happens with navigate({ search: (prev) => ({ ...prev, page: prev.page + 1 }) }). The prev parameter is fully typed and contains the current search params of the route. This functional update form prevents existing search params from being accidentally overwritten. Combined with TanStack Query as the data layer, this produces elegant URL-backed filters: the search params are the single source of truth for filter criteria, and the query key contains the search params directly.

6. Loaders: Fetching Data Before Rendering

Loaders in TanStack Router work similarly to Remix: they run before the route component renders and can fetch data in parallel with parent routes. This eliminates waterfalls, where a component mounts, only then triggers a fetch, waits for the result and afterward renders a child component that triggers yet another fetch. With parallel loaders, the entire data requirement of a route is resolved simultaneously.

Loader data is read with Route.useLoaderData() and is fully typed from the return type of the loader function. Loaders can access the router context via context, where TanStack Query's QueryClient can be provided. The pattern: call queryClient.ensureQueryData() in the loader to populate the cache or use already cached data. The component then reads the data via useSuspenseQuery() from the TanStack Query cache, without an additional network request. The two libraries complement each other perfectly here.

7. Type-Safe Navigation with Link and navigate

The <Link> component of TanStack Router is fully typed. The to prop only accepts known route paths from the router type. Params and search params for the target route are passed as separate props (params, search) and are typed. A link with a missing required param immediately produces a TypeScript error, no longer a runtime problem. activeProps and inactiveProps enable conditional CSS classes based on the active state of the route, which greatly simplifies breadcrumbs and navigation.

Programmatic navigation with router.navigate() or the useNavigate() hook follows the same type safety. The target object with to, params and search is fully checked by the TypeScript compiler. Relative navigation (from: '/products/$productId', to: '../') is likewise type-safe and correctly traverses the route tree, without manual path fiddling. This gives all navigation code in a React application a level of type safety that is fundamentally unreachable with string-based routing.

// ProductsPage.tsx: typed Link, search params, and navigation
import { Link, useNavigate } from "@tanstack/react-router";
import { Route } from "./routes/products";
import { useProducts } from "../hooks/useProducts";

function ProductsPage() {
  // Search params are typed: { category?: string; page: number; sort: "asc" | "desc" }
  const { category, page, sort } = Route.useSearch();
  const navigate = useNavigate({ from: "/products" });
  const { data: products } = useProducts({ category, page, sort });

  const setPage = (nextPage: number) =>
    navigate({ search: (prev) => ({ ...prev, page: nextPage }) });

  const setSort = (nextSort: "asc" | "desc") =>
    navigate({ search: (prev) => ({ ...prev, sort: nextSort, page: 1 }) });

  return (
    <div>
      <div className="flex gap-2 mb-4">
        <button onClick={() => setSort("asc")}>A-Z</button>
        <button onClick={() => setSort("desc")}>Z-A</button>
      </div>

      <ul>
        {products?.map((product) => (
          <li key={product.id}>
            {/* TypeScript error if productId param is missing */}
            <Link
              to="/products/$productId"
              params={{ productId: String(product.id) }}
              activeProps={{ className: "font-bold text-sky-700" }}
            >
              {product.name}
            </Link>
          </li>
        ))}
      </ul>

      <button disabled={page <= 1} onClick={() => setPage(page - 1)}>Back</button>
      <button onClick={() => setPage(page + 1)}>Next</button>
    </div>
  );
}

8. Code Splitting and Lazy Loading

Code splitting in TanStack Router happens via the lazyRouteComponent() function or by separating loader and component into separate files. The route file then contains only the metadata (loader, search param schema, params), while the component is loaded via a dynamic import. This means the initial bundle contains only the router type and the loaders. The actual UI component is only loaded once the route is actually visited.

The file-based routing plugin supports automatic code splitting: if a route file has a component export as its default, it is automatically lazy loaded. The pendingComponent option per route shows a skeleton or loading indicator while loading. Unlike global React Suspense, this is configurable per route. Critical routes can be loaded eagerly, while secondary areas of the application stay lazy. This produces measurably better time-to-interactive values without manual bundle analysis.

9. TanStack Router vs. React Router v6 Compared

The comparison shows where TanStack Router has structural advantages over React Router v6 and where its limits lie.

React Router v6 remains the safe choice for teams with a large existing codebase and abundant resources on the internet. TanStack Router is the right choice for new TypeScript projects where type safety in navigation and URL state is a serious architectural goal. Migrating from React Router to TanStack Router is costly; for new projects, starting with TanStack Router pays off from the very beginning.

10. Summary

TanStack Router solves the fundamental type safety problem of routing in TypeScript React applications. Routes as typed objects with known params and search params make it impossible to create a link to the wrong route or with wrong params. The TypeScript compiler prevents it. Loaders eliminate data fetch waterfalls without a framework. Search params with schema and default values replace manual URLSearchParams parsing. File-based routing with the Vite plugin reduces route configuration to the bare minimum.

The most important design decision for teams: TanStack Router is ideal for new TypeScript projects where type safety is a core goal, and for teams that already use TanStack Query and want to benefit from seamless loader integration. The learning curve is steeper than with React Router v6, but it pays off quickly through fewer runtime errors and a better developer experience. Routing turns from a frequent source of errors into a statically verified part of the architecture.

11. FAQ: TanStack Router and Type-Safe Routing