/react-router-typesafe

just the way you wanted React Router to work with TypeScript.

Primary LanguageTypeScript

React Router Typesafe

React Router Typesafe is a minimal (235 bytes gzipped) patch built upon react-router to add type-safety via the use of generics. It brings type functionality closer to Remix, the full-stack framework from the same authors.

Getting Started

Install the package:

npm install react-router-typesafe

Replace your imports from react-router to react-router-typesafe:

- import { defer, useLoaderData, useActionData } from "react-router";
+ import { defer, useLoaderData, useActionData } from "react-router-typesafe";

Usage

useLoaderData / useActionData

import { useLoaderData, useActionData, LoaderFunction, ActionFunction } from 'react-router-typesafe';

const loader = (() => ({ message: 'Hello World' })) satisfies LoaderFunction;

const action = (() => ({ ok: true })) satisfies ActionFunction;

const Component = () => {
	const data = useLoaderData<typeof loader>();
	const actionData = useActionData<typeof action>();

	return <div>{data.message}</div>;
};

Warning Do not annotate the type of the loader/action function. It will break the type-safety. Instead rely on either the satisfies keyword from Typescript 4.9 onwards, or the makeLoader / makeAction utilities proveded by this library.

Utilities

makeLoader / makeAction

The makeLoader and makeAction utils replace the need for the satisfies keyword without adding any runtime overhead.

import { makeLoader, makeAction } from 'react-router-typesafe';

const loader = makeLoader(() => ({ message: 'Hello World' }));

const action = makeAction(() => ({ ok: true }));

typesafeBrowserRouter ❇️ NEW

The typesafeBrowserRouter is a wrapper around createBrowserRoute that returns a href function in addition to the routes.

It’s easy to incrementally adopt, and you can use href anywhere, not just in <Link> components.

Set up your routes like this:

- import { createBrowserRouter } from "react-router-dom";
+ import { typesafeBrowserRouter } from "react-router-typesafe";

- export const router = createBrowserRouter([
+ export const { router, href } = typesafeBrowserRouter([
  { path: "/", Component: HomePage },
  { path: "/projects/:projectId", Component: ProjectPage },
]);
  • ✅ No need to change your existing <Link> components.
  • ✅ URL params are inferred and type-checked.
  • ✅ Supports query params and URL hash
  • ✅ Refactor-friendly: Rename Symbol on the route path and it’ll be updated everywhere.

Then use href to generate URLs:

import { Link } from 'react-router-dom';
import { href } from './router';

const ProjectCard = (props: { id: string }) => {
	return (
		<Link to={href({ path: '/projects/:projectId', params: { projectId: props.id } })}>
			<p>Project {projectId}</p>
		</Link>
	);
};

Contributing

Feel free to improve the code and submit a pull request. If you're not sure about something, create an issue first to discuss it.

Functions

Status Utility Before After
defer Response Generic matching the first argument
json Response Serialized data passed in
useLoaderData unknown Generic function with the type of the loader function passed
useActionData unknown Generic function with the type of the action function passed
useRouteLoaderData unknown Generic function with the type of the loader function passed
NEW makeLoader Wrapper around satisfies for ergonomics
NEW makeAction Wrapper around satisfies for ergonomics
NEW typesafeBrowserRouter Extension of createBrowserRouter

Patched components

Status Component Before After
<Await> children render props would be typed as any Generic component makes render props typesafe

About

React Router is developed and maintained by Remix Software and many amazing contributors.