React Router Typed Object

Bringing full typesafety to your React Router configurations

Introduction

React Router Typed Object is a helper library for React Router that brings complete typesafety to your route configurations. It enables you to define your routes in a way that TypeScript can infer all the necessary types, ensuring that all router references are consistent and safe across your codebase. This is especially beneficial in large applications with complex routing structures, where maintaining typesafety can greatly reduce errors and improve developer productivity.

By using React Router Typed Object, you can leverage the power of TypeScript to catch errors at compile time, assist in refactoring, and provide better autocompletion and documentation within your code editor. Check more details and examples in the Typesafe references and refactorings docs section.

Features

• Seamless Integration: Works with exact react-router's RouteObject type and react-router-dom's "createRouter*" functions.
• Typesafe Route Definitions: Automatically infer types from your route configurations.
• Path Parameter Handling: Define routes with dynamic parameters and get type-checked path generation.
• Search Parameter Validation: Use any validation library you like to define and validate search parameters.
• Type-Safe useParams Hook: Access route parameters with full type safety using the built-in useParams hook.

Installation

To install React Router Typed Object, use npm or yarn:

1npm install react-router-typed-object @remix-run/router

@remix-run/router explicit installation is needed to allow correct type inference.

Usage

Here's how you can use React Router Typed Object in your project.

Defining Routes with inferRouteObject

The inferRouteObject function allows you to define your routes and automatically infer their types.

1import { inferRouteObject } from "react-router-typed-object";
2
3export const ROUTES = inferRouteObject({
4  path: "a",
5  children: [
6    { path: "b" },
7    {
8      path: "c",
9      children: [{ children: [{ children: [{ path: "d" }] }] }],
10    },
11  ],
12});

This will create a ROUTES object that contains typed paths for all nested routes.

Generating Paths with Parameters

You can define routes with path parameters, and inferRouteObject will ensure that you provide the correct parameters when generating paths.

1export const ROUTES = inferRouteObject({
2  path: "a/:b",
3  children: [{ path: "c/:d" }],
4});
5
6const path = ROUTES["/a/:b/c/:d"].path({ b: "B", d: "D" });
7// path is "/a/B/c/D"

If you try to omit required parameters or provide incorrect ones, TypeScript will show an error.

Handling Search Parameters with Validation

You can define search parameters using any type predicate, which give you both typesafety and runtime validation.

1import { z } from "zod";
2
3export const ROUTES = inferRouteObject({
4  path: "a/:b",
5  children: [
6    {
7      path: "c/:d",
8      searchParams: z.object({
9        z: z.string(),
10        q: z.string().optional(),
11      }).parse, // NOTE the `.parse`, we need only a validation function
12    },
13  ],
14});
15
16const path = ROUTES["/a/:b/c/:d"].path({ b: "B", d: "D", z: "Z" });
17// path is "/a/B/c/D?z=Z"

If you provide invalid search parameters, the validation function will throw an error at runtime, ensuring your app only navigates to valid URLs.

Using typesafe paths with a router

"ROUTES" is your source of truth. You can use it to get a typesafe access to your routes in all other related APIs.

1<Route path={ROUTES["/a/:b/c/:d"].path.pattern} />

OR, of course:

1import { createBrowserRouter } from "react-router-dom";
2
3export const router = createBrowserRouter([ROUTES]);

1const navigate = useNavigate();
2const toD = (b: string, d: string) => {
3  navigate(ROUTES["/a/:b/c/:d"].path({ b, d }));
4};
5
6<a onClick={() => toD("B", "D")}>Go to D</a>;

Using the useParams hook

The useParams hook allows you to access route parameters with full type safety:

1function MyComponent() {
2  // Get parameters with type safety
3  const params = ROUTES["/a/:b/c/:d"].path.useParams();
4  
5  // params.b and params.d are typed as string
6  // If the route has search parameters, they are also included in the params object
7  
8  return (
9    <div>
10      <h1>Parameter B: {params.b}</h1>
11      <h1>Parameter D: {params.d}</h1>
12    </div>
13  );
14}

You can also provide fallback values for missing parameters:

1function MyComponent() {
2  // Provide fallback values for missing parameters
3  const params = ROUTES["/a/:b/c/:d"].path.useParams({ b: "default-b", d: "default-d" });
4  
5  return (
6    <div>
7      <h1>Parameter B: {params.b}</h1>
8      <h1>Parameter D: {params.d}</h1>
9    </div>
10  );
11}

The useParams hook will:

1. Return the current route parameters with full type safety
2. Throw a runtime error if required parameters are missing and not provided in the fallback
3. Provide TypeScript compile-time errors if you try to access parameters that don't exist

Navigating with built in createRouter

You can use your "ROUTES" object to get a typesafe access to your routes

The createRouter function creates a router instance with typesafe navigate method which added to every "path".

1import { createRouter } from "react-router-typed-object";
2import { z } from "zod";
3
4const ROUTER = createRouter([
5  {
6    path: "a",
7    children: [
8      {
9        path: ":b/c/:d",
10        searchParams: z.object({ z: z.string() }).parse,
11      },
12    ],
13  },
14]);
15
16ROUTER["/a/:b/c/:d"].path.navigate({ b: "B", d: "D", z: "Z" });
17// `location.href` is "/a/B/c/D?z=Z"

The .navigate() method of a router path is just a tiny bind function from the path to router navigate method.

Typesafe references and refactorings

The motivation behind creating this library stemmed from working on a large legacy project with a massive route configuration exceeding 1,000 lines of code. Managing and maintaining such a large configuration was challenging. It was easy to make mistakes like creating duplicate paths or unintentionally removing or modifying routes that were used elsewhere in the application.

React Router Typed Object addresses these issues by allowing developers to define a strict list of all routes with full typesafety. The "path" property becomes a crucial element to synchronize type references between route usages and route definitions. With this library, you can use TypeScript's powerful tooling to find all route usages from the configuration or locate the relevant configuration part from a usage point. This ensures consistency and reduces the likelihood of errors in your routing logic.

Open this example on StackBlitz:

API Reference

inferRouteObject(routeConfig, basename = '')

Generates a typesafe routes object from the given route configuration. The configuration is exactly import { type RouteObject } from "react-router", but with additional searchParams property with a validation function.

• Parameters:
  • routeConfig: An object representing the route configuration. It is same object from original React Router (import { type RouteObject } from "react-router"). Each route can include path, children, and additional searchParams validation function.
  • basename: optional starting path.
• Returns: The same route object with additional "\${string}" properties which includes full routes paths in any depth of the config.

createRouter(routeConfig, options)

Creates a router instance with typesafe navigation methods.

• Parameters:
  • routeConfig: The same route configuration used in inferRouteObject.
  • options:
    • all original options from createBrowserRouter.
    • basename: optional starting path.
    • createRouter: optional router creation function, defaults to createBrowserRouter.
• Returns: A router instance with navigation methods and all "\${string}" routes from inferRouteObject

path.useParams(fallback?)

A hook that returns the current route parameters with full type safety.

• Parameters:
  • fallback: Optional object containing fallback values for missing parameters.
• Returns: An object containing all route parameters (path and search parameters) with proper types.
• Throws: Runtime error if required parameters are missing and not provided in the fallback.
• Type Safety: Provides TypeScript compile-time errors if you try to access parameters that don't exist.