react-router-typesafe-routes

Routes can be nested to create hierarchical URL structures. Child routes inherit properties from their parents. You can define children in two ways:

1. Inlined: Defining children directly within the route() configuration.
2. Uninlined: Defining a route separately and passing it to the children property of another route. Note that an uninlined route is a standalone route and does not automatically know about its parent's context unless it is explicitly assigned as a child.

Important: Child route names cannot start with $ to avoid conflicts with the library's internal API.

import { route } from "react-router-typesafe-routes";

// Inlined nesting
const user = route({ 
  path: "user/:id", 
  children: { details: route({ path: "details" }) } 
});

console.log(user.$path()); // "/user/:id"
console.log(user.details.$path()); // "/user/:id/details"

// Uninlined nesting
const details = route({ path: "details" });
const user = route({ path: "user/:id", children: { details } });

console.log(user.details.$path()); // "/user/:id/details"
console.log(details.$path()); // "/details"

The library provides end-to-end type safety for all React Router v7 route parts:

• Pathname params
• Search params (including multiple identical keys)
• State
• Hash

It works by defining a route tree that handles both the building (serialization) and parsing/validating (deserialization) of URL parts.

Key Concepts:

• Validation: You can use built-in types (like string(), number(), boolean()) or external libraries (Zod, Yup, Standard Schema).
• Error Handling: In built-in types, parsing errors are caught and replaced with undefined. You can also configure default values or throw errors.
• Inheritance: Child routes automatically inherit all parameters (search, state, etc.) defined in their parent routes.
• No Unsafe Casts: The library ensures type safety without using any or unsafe type assertions.
• Non-destructive: It does not alter the React Router API and supports nested routes and relative links.

You can create reusable route fragments (pathless routes) to share parameter or search parameter types across multiple routes.

• Pathless Routes: Define a route without a path property to act as a type fragment.
• Composition: Use the compose array in a route definition to include types from these fragments.
• Usage: Use useTypedParams or useTypedSearchParams with the fragment to extract the shared types in your components.

import { route, useTypedParams, useTypedSearchParams } from "react-router-typesafe-routes";

const fragments = {
  id: route({
    params: { id: number() },
  }),
  query: route({
    searchParams: { query: string() },
  }),
};

const root = route({
  searchParams: { utm_campaign: string() },
  compose: [fragments.id],
  children: {
    user: route({ path: "user/:id", compose: [fragments.query] }),
    post: route({ path: "post/:id" }),
    about: route({ path: "about" }),
  },
});

const { id } = useTypedParams(fragments.id);
const [{ query }] = useTypedSearchParams(fragments.query);
const [{ utm_campaign }] = useTypedSearchParams(root);

Once your route tree is defined, use the generated $path() methods to provide paths to React Router's <Route /> components.

Absolute vs Relative Paths:

• Absolute: Use root.path.$path() for standard absolute routing.
• Relative: Use root.path.$path({ relative: true }) for relative routing. When using relative paths, you must use the $ symbol to indicate the start of the path pattern (e.g., root.user.$.post.$path(...)).

Note: Leading slashes in path patterns are forbidden to ensure the library correctly governs route relativity.

import { Route, Routes } from "react-router";
import { root } from "./path/to/routes";

// Absolute paths
<Routes>
  <Route path={root.user.$path()} element={<User />}>
    <Route path={root.user.post.$path()} element={<Post />} />
  </Route>
</Routes>

// Relative paths
<Routes>
  <Route path={root.user.$path({ relative: true })} element={<User />}>
    <Route path={root.user.$.post.$path({ relative: true })} element={<Post />} />
  </Route>
</Routes>

When using useTypedSearchParams or $buildSearch, you can preserve search parameters that are not explicitly typed by the current route.

1. In JSX (Link component): Pass the raw search params from useSearchParams() to the untypedSearchParams option in $buildSearch.
2. In event handlers (setTypedSearchParams): Set the untypedSearchParams option to true in the options object to ensure parameters not defined in the route schema are kept.

import { route, string, number, useTypedSearchParams } from "react-router-typesafe-routes";
import { useSearchParams } from "react-router";

export const searchParamsFragment = route({
  searchParams: {
    search: string(),
    page: number(),
  },
});

// In a component body
const [typedSearchParams, setTypedSearchParams] = useTypedSearchParams(searchParamsFragment);
const rawSearchParams = useSearchParams();

// In JSX
<Link
  to={searchParamsFragment.$buildSearch({
    searchParams: {
      ...typedSearchParams,
      page: 1,
    },
    untypedSearchParams: rawSearchParams,
  })}
>
  Click
</Link>;

// In an event handler
setTypedSearchParams(
  (prevParams) => ({
    ...prevParams,
    page: 1,
  }),
  {
    untypedSearchParams: true,
  },
);

When upgrading to the Universal Types syntax (introduced in v2.0.0), the way route parameters and state are defined changes from specific type functions (like stringType) to a chainable method syntax (like string()).

Key Syntax Changes

Important Behavioral Differences

1. State Validation: In the new syntax, for state fields, the value (or its parts) is only validated; it is not stringified or parsed.
2. Handling Undefined: With the new syntax, if you use .default() or .defined(), undefined cannot be returned.
3. Array Behavior:
   • In the new syntax, arrays are always defined.
   • string().array() always returns an array. Invalid items are replaced with undefined (Note: as of v2.0.0, undefined values are omitted from the resulting array).
   • If you need the array to fail if any item is invalid, use string().defined().array(). This will throw an error if any item is absent or invalid.
   • There is no direct equivalent for the old arrayOfType(/* */)([]) or arrayOfType(/* */)(throwable) patterns because arrays are now always defined, and error handling is managed at the item level rather than the array level.

To integrate with react-router-dom, use the $path() method from your route objects to populate the path prop of <Route /> components.

Absolute Paths

By default, $path() returns an absolute path pattern (starting with /). This is the recommended approach for most use cases.

Relative Paths

If you need to use relative paths (e.g., inside a nested <Routes /> or when dealing with specific React Router quirks), use $path({ relative: true }). This returns a path without a leading slash and without intermediate stars (*). To access child routes relatively, use the $ property of the parent route.

Note: When rendering a parent route that contains nested <Routes />, you must append /* to the parent's path pattern in the library configuration.

import { Route, Routes } from "react-router-dom";
import { route } from "react-router-typesafe-routes";

const user = route({ path: "user/:id/*", children: { details: route({ path: "details" }) } });

// Parent Route
<Routes>
  <Route path={user.$path()} element={<User />} />
</Routes>

// Inside <User /> component
<Routes>
  <Route path={user.$.details.$path()} element={<UserDetails />} />
</Routes>

Use the route function to define your application's routing structure. You can define global parameters at a root level (even for pathless routes) which will then be inherited by all children.

Common modifiers for built-in types:

• .default(value): Provides a fallback value if the parameter is absent or invalid.
• .defined(): Makes a parameter required (will throw upon parsing if absent).

Example of a route tree with nested children, search params, hash, and state:

import { route, string, number, boolean, union } from "react-router-typesafe-routes";

const root = route({
  // Global search param with a default value
  searchParams: { utm_campaign: string().default("default_campaign") },
  children: {
    user: route({
      path: "user/:userId",
      params: { userId: number() },
      hash: union(["info", "comments"]),
      state: { fromUserList: boolean() },
      children: {
        post: route({ path: "post/:postId?" }),
      },
    }),
  },
});

Use $buildPath to generate a URL string and $buildState to generate the state object for <Link /> or navigate(). This ensures that all required parameters, search params, and hashes are provided and correctly typed.

• $buildPath: Accepts params, searchParams, hash, and an optional relative flag.
• $buildState: Accepts the state object defined in your route configuration.

import { Link } from "react-router";
import { root } from "./path/to/routes";

// Absolute link
<Link
  to={root.user.post.$buildPath({
    params: { userId: 1, postId: "abc" },
    searchParams: { utm_campaign: "campaign" },
    hash: "comments",
  })}
  state={root.user.post.$buildState({ fromUserList: true })}
>
  /user/1/post/abc?utm_campaign=campaign#comments
</Link>

// Relative link
<Link
  to={root.user.$.post.$buildPath({
    relative: true,
    params: { postId: "abc" },
    searchParams: { utm_campaign: "campaign" },
    hash: "info",
  })}
  state={root.user.post.$buildState({ fromUserList: false })}
>
  post/abc?utm_campaign=campaign#info
</Link>