Typesafe routing for React Router apps.
npm install safe-routesType-safe helper for manipulating internal links in your React Router apps.
> [!note]
> remix-routes has been renamed to safe-routes. If you are looking for the documentation of remix-routes, please refer to here.
>
> Please refer to the upgrading guide if you are upgrading from remix-routes.
- Typed URL generation
- Appending query string
- Typed query string
- Typed route ids
- Basename support
``bash`
$ npm add safe-routes
Add safeRoutes plugin to your vite.config.ts:
`javascript
import { defineConfig } from "vite";
import { reactRouter } from "@react-router/dev/vite";
import { safeRoutes } from 'safe-routes/vite';
export default defineConfig({
plugins: [
reactRouter(),
safeRoutes(),
],
});
`
Supported config options:
- strict: boolean
-
Add safe-routes typegen to the typecheck script:
`patch`
- "typecheck": "react-router typegen && tsc --build --noEmit"
+ "typecheck": "react-router typegen && safe-routes typegen && tsc --build --noEmit"
`typescript
import { redirect } from 'react-router';
import { $path } from 'safe-routes'; // <-- Import magical $path helper from safe-routes.
export const action = async ({ request }) => {
let formData = await request.formData();
const post = await createPost(formData);
return redirect($path('/posts/:id', { id: post.id })); // <-- It's type safe.
};
`
`typescript
import { $path } from 'safe-routes';
$path('/posts/:id', { id: 6 }, { version: 18 }); // => /posts/6?version=18
$path('/posts', { limit: 10 }); // => /posts?limit=10
// You can pass any URLSearchParams init as param
$path('/posts/delete', [['id', 1], ['id', 2]]); // => /posts/delete?id=1&id=2
`
Define type of query string by exporting a type named SearchParams in route file:
`typescript
// app/routes/posts.tsx
export type SearchParams = {
view: 'list' | 'grid',
sort?: 'date' | 'views',
page?: number,
}
`
`typescript
import { $path } from 'safe-routes';
// The query string is type-safe.
$path('/posts', { view: 'list', sort: 'date', page: 1 });
`
You can combine this feature with zod and remix-params-helper to add runtime params checking:
`typescript
import { z } from "zod";
import { getSearchParams } from "remix-params-helper";
const SearchParamsSchema = z.object({
view: z.enum(["list", "grid"]),
sort: z.enum(["price", "size"]).optional(),
page: z.number().int().optional(),
})
export type SearchParams = z.infer
export const loader = async (request) => {
const result = getSearchParams(request, SearchParamsSchema)
if (!result.success) {
return json(result.errors, { status: 400 })
}
const { view, sort, page } = result.data;
}
`
> [!NOTE]
> This function has been marked @deprecated in favor of React Router'sparams
> built-in type-safety, which provides strongly typed to loaders,
> actions, and components. This helper has been kept primarily to assist in
> incremental migration.
`typescript
import { useParams } from "react-router";
import { $params } from 'safe-routes'; // <-- Import $params helper.
export const action = async ({ params }) => {
const { id } = $params("/posts/:id/update", params) // <-- It's type safe, try renaming id param.
// ...
}
export default function Component() {
const params = useParams();
const { id } = $params("/posts/:id/update", params);
...
}
`
safe-routes exports the RouteId type definition with the list of all valid route ids for your repository, and has a helper function $routeId that tells typescript to restrict the given string to one of the valid RouteId values.
`typescript
import type { RouteId } from 'safe-routes';
import type { loader as postsLoader } from './_layout.tsx';
import { useRouteLoaderData } from 'react-router';
import { $routeId } from 'safe-routes';
export default function Post() {
const postList = useRouteLoaderData
}
`
Basename is supported out of the box. If you have set a basename in your vite.config.ts and react-router.config.ts, safe-routes will automatically prepend the basename to the generated URLs.
`typescript
// react-router.config.ts
import type { Config } from "@react-router/dev/config";
export default {
basename: "/blog",
} satisfies Config;
`
`typescript
import { $path } from 'safe-routes';
$path('/posts/:id', { id: 6 }); // => /blog/posts/6
``