路由模块类型安全
本页目录

路由模块类型安全

React Router 会生成特定于路由的类型,以便为 URL 参数、loader 数据等提供类型推断。如果您没有从模板开始构建项目,本指南将帮助您进行设置。

要了解有关 React Router 中类型安全如何工作的更多信息,请查看 类型安全解释

1. 将 .react-router/ 添加到 .gitignore

React Router 会在您的应用根目录中生成类型文件到 .react-router/ 目录。此目录由 React Router 完全管理,应添加到 .gitignore 中。

.react-router/

2. 在 tsconfig 中包含生成的类型

编辑您的 tsconfig 文件,让 TypeScript 使用生成的类型。此外,还需要配置 rootDirs,以便可以将这些类型作为路由模块的相对同级文件导入。

{
  "include": [".react-router/types/**/*"],
  "compilerOptions": {
    "rootDirs": [".", "./.react-router/types"]
  }
}

如果您的应用使用多个 tsconfig 文件,您需要在包含应用目录的那个文件中进行这些更改。例如,node-custom-server 模板包含 tsconfig.jsontsconfig.node.jsontsconfig.vite.json。由于是 tsconfig.vite.json 包含应用目录,因此它负责为路由模块类型安全设置 .react-router/types

3. 在类型检查前生成类型

如果您希望将类型检查作为独立的命令运行 — 例如,作为持续集成流程的一部分 — 您需要确保在运行类型检查之前生成类型。

{
  "scripts": {
    "typecheck": "react-router typegen && tsc"
  }
}

4. 为 AppLoadContext 添加类型

扩展应用的 Context 类型

要定义您的应用的 context 类型,请在项目内的 `.ts` 或 `.d.ts` 文件中添加以下内容

import "react-router";
declare module "react-router" {
  interface AppLoadContext {
    // add context properties here
  }
}

5. 仅类型自动导入(可选)

当自动导入 Route 类型辅助函数时,TypeScript 将生成

import { Route } from "./+types/my-route";

但如果您启用 verbatimModuleSyntax

{
  "compilerOptions": {
    "verbatimModuleSyntax": true
  }
}

那么,您将自动获得 import 语句中的 type 修饰符

import type { Route } from "./+types/my-route";
//     ^^^^

这有助于像打包器这样的工具检测仅类型模块,这些模块可以安全地从打包中排除。

总结

React Router 的 Vite 插件会在您编辑路由配置 (routes.ts) 时自动将类型生成到 .react-router/types/ 目录。这意味着您只需要运行 react-router dev(或您自定义的开发服务器),即可在路由中获得最新的类型。

请查阅我们的 类型安全说明,了解如何将这些类型集成到你的路由中。

文档和示例 CC 4.0