safe-routes

用于操作 React Router 应用中内部链接的类型安全助手。

[!note] remix-routes 已重命名为 safe-routes。 如果您正在查找 remix-routes 的文档，请参阅此处。

如果您是从 remix-routes 升级，请参阅升级指南。

亮点

• 类型化的 URL 生成
• 追加查询字符串
• 类型化的查询字符串
• 类型化的路由 ID
• Basename 支持

安装

$ npm add safe-routes

设置

将 safeRoutes 插件添加到您的 vite.config.ts

import { defineConfig } from "vite";
import { reactRouter } from "@react-router/dev/vite";
import { safeRoutes } from 'safe-routes/vite';

export default defineConfig({
  plugins: [
    reactRouter(),
    safeRoutes(),
  ],
});

支持的配置选项

• strict: boolean
• outDir: string

将 safe-routes typegen 添加到 typecheck 脚本

- "typecheck": "react-router typegen && tsc --build --noEmit"
+ "typecheck": "react-router typegen && safe-routes typegen && tsc --build --noEmit"

用法

类型化的 URL 生成

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.
};

追加查询字符串

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

类型化的查询字符串

通过在路由文件中导出名为 SearchParams 的类型来定义查询字符串的类型

// app/routes/posts.tsx

export type SearchParams = {
  view: 'list' | 'grid',
  sort?: 'date' | 'views',
  page?: number,
}

import { $path } from 'safe-routes';

// The query string is type-safe.
$path('/posts', { view: 'list', sort: 'date', page: 1 });

您可以将此功能与 zod 和 remix-params-helper 结合使用，以添加运行时参数检查

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<typeof SearchParamsSchema>;

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;
}

类型化的路由 ID

safe-routes 导出 RouteId 类型定义，其中包含您的存储库的所有有效路由 ID 列表，并具有一个辅助函数 $routeId，该函数告诉 typescript 将给定的字符串限制为有效的 RouteId 值之一。

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<typeof postsLoader>($routeId('routes/posts/_layout'));
}

Basename 支持

开箱即用地支持 Basename。 如果您在 vite.config.ts 和 react-router.config.ts 中设置了 basename，safe-routes 将自动将 basename 添加到生成的 URL。

// react-router.config.ts
import type { Config } from "@react-router/dev/config";

export default {
  basename: "/blog",
} satisfies Config;

import { $path } from 'safe-routes';

$path('/posts/:id', { id: 6 }); // => /blog/posts/6

许可证

MIT