# React 路由器到 TanStack 路由器的迁移使用基于文件的路由将 React 应用程序从 React Router 迁移到 TanStack Router。此技能为增量迁移和干净迁移提供了结构化方法。 ## 关键规则 **始终：** * 在 `src/routes/` 目录中使用基于文件的路由 * 在所有钩子中使用 `from` 参数以确保类型安全 (`useParams({ from: '/path' })`) * 使用 `@tanstack/zod-adapter` 验证 Zod 模式的搜索参数 * 在创建路由之前配置构建工具插件 * 注册路由器类型以进行完整的 TypeScript 推理 * 使用`fallback()`包装器作为可选的搜索参数 **从不：** * 编辑`routeTree.gen.ts`（自动生成的文件） * 在迁移期间在新代码中使用 React Router hooks * 忘记“from”参数（失去类型安全） * 对搜索参数使用仅字符串验证 * 跳过构建插件配置 ## 依赖关系 # 核心依赖面包添加@tanstack/react-router @tanstack/zod-adapter # 构建插件（根据您的捆绑程序选择一个） Bun 添加-d @tanstack/router-plugin # 可选集成 Bun add nuqs # URL状态管理 Bun add @sentry/react # 使用路由器集成进行错误跟踪 ## 迁移阶段 ### 第 1 阶段：评估 **审核现有的 React Router 使用情况：** # 查找所有 React Router 导入 grep -r“来自'react-router”src / --include =“*.tsx”--include =“*.ts” grep -r '来自“react-router”src/ --include="*.tsx" --include="*.ts" # 查找钩子的用法 grep -r "useParams\|useSearchParams\|useNavigate\|useLocation\|useMatch" src/ **文件：** * React Router 版本（v5 或 v6） * 路线数量 * `useParams` 使用计数 * `useSearchParams` 使用计数 * `useNavigate` 使用计数 * 自定义链接组件 * 路线守卫/保护路线 * 现有路线结构 ### 第 2 阶段：设置 **1\.配置构建工具** 有关完整配置，请参阅 [references/build-configuration.md]()。 **Rspack/Rsbuild：** // rsbuild.config.ts 从 '@tanstack/router-plugin/rspack' 导入 { TanStackRouterRspack }；导出默认值{ 工具：{ rspack：（配置）=> { config.plugins?.push( TanStackRouterRspack({ 目标：'反应'，自动代码分割：真，路线目录：'./src/routes', 生成的RouteTree: './src/routeTree.gen.ts', quoteStyle: '单', 分号：正确， }) ）； // 防止重建循环 config.watchOptions = { 忽略: ['**/routeTree.gen.ts'] }; 返回配置； }, }, }; **投票：** // vite.config.ts 从 '@tanstack/router-plugin/vite' 导入 { TanStackRouterVite }；导出默认的defineConfig({ 插件：[ TanStackRouterVite({ 目标：'反应'，自动代码分割：真，路线目录：'./src/routes', 生成的RouteTree: './src/routeTree.gen.ts', }), 反应（）， ], }); **2\.配置 Linter** // biome.jsonc 或 eslint 配置 { “文件”：{ “忽略”：[“**/routeTree.gen.ts”] }, “覆盖”：[ { “包括”：[“**/路线/**/*”]， “短绒”：{ “规则”：{ “风格”：{ "useFilenamingConvention": "off" // 允许 $param.tsx 命名 } } } } ] } **3\.创建路线目录** mkdir -p src/路由 ### 第 3 阶段：路由器创建 **创建路由器实例：** // src/app.tsx 从'@tanstack/react-router'导入{createRouter，RouterProvider}；从 '@tanstack/react-query' 导入 { QueryClient, QueryClientProvider }; 从'./routeTree.gen'导入{routeTree}；从 './components/misc/not-found-page' 导入 { NotFoundPage }； const queryClient = new QueryClient(); 常量路由器 = createRouter({ 路线树，上下文：{ 基本路径： getBasePath(), 查询客户端， }, 基本路径：getBasePath(), 尾随斜杠：'从不'，默认NotFoundComponent：NotFoundPage， }); // 注册路由器类型以进行完整的 TypeScript 推理声明模块'@tanstack/react-router'{ 接口寄存器{ 路由器：路由器类型； } // 扩展 HistoryState 以实现类型化导航状态接口历史状态{ // 在此处添加您的自定义状态属性 returnUrl？：字符串；文档ID？：字符串；文档名称？：字符串； } } 导出函数 App() { 返回（）； } **定义路由器上下文类型：** // src/routes/__root.tsx 从 '@tanstack/react-query' 导入类型 { QueryClient }；导出类型 RouterContext = { 基本路径：字符串；查询客户端：查询客户端； }; ### 第 4 阶段：路由迁移 **创建根布局：** // src/routes/__root.tsx 从 '@tanstack/react-router' 导入 { createRootRouteWithContext, Outlet }; 从 '@tanstack/react-router-devtools' 导入 { TanStackRouterDevtools }；从 '@tanstack/react-query' 导入类型 { QueryClient }；从 'nuqs/adapters/tanstack-router' 导入 { NuqsAdapter }；导出类型 RouterContext = { 基本路径：字符串；查询客户端：查询客户端； }; 导出 const 路由 = createRootRouteWithContext()({ 组件：根布局， }); 函数根布局（）{ 返回（ <> <错误边界> <应用程序布局> <出口/> {process.env.NODE_ENV === '开发' && ( )} ）； } **基于文件的路由结构：** src/路线/ ├── __root.tsx # 根布局 ├──index.tsx#/（根重定向） ├── 概述/ │ └── index.tsx # /概述 ├── 主题/ │ ├── index.tsx # /topics │ └── $主题名称/ │ ├── index.tsx # /topics/:主题名称 │ └── edit.tsx # /topics/:topicName/edit ├── 安全/ │ ├── index.tsx # /安全（重定向） │ ├── acls/ │ │ ├── index.tsx # /security/acls │ │ ├── create.tsx # /security/acls/create │ │ └── $aclName/ │ │ └──details.tsx # /security/acls/:aclName/details 有关完整模板，请参阅 [references/route-templates.md]()。 ### 第 5 阶段：钩子迁移反应路由器| TanStack路由器 ---|--- `useParams()` | `useParams({ 来自: '/path/$param' })` `useSearchParams()` |带有 Zod 验证的“routeApi.useSearch()” `useNavigate()` | `useNavigate({ from: '/path' })` `useLocation()` | `useLocation()`（相同的 API） `<链接到=“/路径”>` | ``（类型安全） `<导航到=“/path”/>` | `<导航到=“/路径”/>` 有关详细的前后示例，请参阅 [references/migration-patterns.md]()。 **导航状态：** 使用“HistoryState”在路由之间传递类型化状态： // 使用状态进行导航常量导航 = useNavigate(); 导航（{ 至：'/documents/$documentId', 参数: { 文档 ID }, 状态：{ returnUrl: 位置.路径名, documentName: '我的文档', }, }); // 读取目标组件中的状态从'@tanstack/react-router'导入{useLocation}；函数文档页面（）{ const 位置 = useLocation(); const { returnUrl, documentName } = location.state; // 使用状态值... } **useParams迁移：** // 之前（反应路由器）从'react-router-dom'导入{useParams}； const { id } = useParams<{ id: string }>(); // 之后（TanStack 路由器）从'@tanstack/react-router'导入{useParams}； const { id } = useParams({ 来自: '/items/$id' }); **使用带有 Zod 验证的搜索：** // 在路由文件中从“@tanstack/zod-adapter”导入{后备，zodValidator}；从 'zod' 导入 { z }； const searchSchema = z.object({ 选项卡：后备（z.string（）.可选（），未定义），页面：后备（z.number（）.可选（），1）， q：后备（z.string（）.可选（），未定义）， }); 导出 const 路由 = createFileRoute('/items/')({ validateSearch: zodValidator(searchSchema), 组件：项目页面， }); // 在组件中从 '@tanstack/react-router' 导入 { getRouteApi, useNavigate }; const RouteApi = getRouteApi('/items/'); 函数 ItemsPage() { const { tab, page, q } = routeApi.useSearch(); const navigation = useNavigate({ from: '/items/' }); const handleTabChange = (newTab: string) => { 导航({ 搜索: (上一个) => ({ ...上一个, 选项卡: newTab }) }); }; } ### 第 6 阶段：测试 **创建测试实用程序：** // src/test-utils.tsx 从 '@tanstack/react-router' 导入 { createMemoryHistory, createRouter, RouterProvider }; 从 '@tanstack/react-query' 导入 { QueryClient, QueryClientProvider }; 从 '@testing-library/react' 导入 { render, type RenderOptions }; 从'./routeTree.gen'导入{routeTree}；从 './routes/__root' 导入类型 { RouterContext }；接口 RenderWithFileRoutesOptions 扩展 Omit { 初始位置？：字符串； routerContext?: 部分; } 导出函数 renderWithFileRoutes( ui：React.ReactElement |空=空， { 初始位置 = '/', routerContext = {}, ...renderOptions }: RenderWithFileRoutesOptions = {} ）{ const queryClient = 新的 QueryClient({ defaultOptions: { 查询: { 重试: false } }, }); 常量路由器 = createRouter({ 路线树，历史记录：createMemoryHistory({initialEntries: [initialLocation] }), 上下文：{ basePath：''，queryClient，...routerContext }， }); 函数 Wrapper({ 孩子 }: { 孩子: React.ReactNode }) { 返回（ {children} ）； } 返回{ ...render(ui ??

, { 包装器: 包装器, ...renderOptions }), 路由器， }; } 导出异步函数 renderRoute(location: string, options?: RenderWithFileRoutesOptions) { const 结果 = renderWithFileRoutes(null, {initialLocation: 位置, ...选项 }); 等待结果.router.load(); 返回结果； } **配置Vitest：** // vitest.config.integration.mts 从 '@tanstack/router-plugin/vite' 导入 { tanstackRouter }；导出默认的defineConfig({ 插件：[ tanstackRouter({ 目标：'反应'，路线目录：'./src/routes', 生成的RouteTree: './src/routeTree.gen.ts', }), 反应（）， ], 测试：{ 环境：'jsdom'， setupFiles: ['./src/test/setup.ts'], }, }); ### 第 7 阶段：集成 **哨兵集成：** // src/app.tsx 从“@sentry/react”导入*作为哨兵； Sentry.init({ dsn: process.env.SENTRY_DSN, 集成：[ Sentry.tanstackRouterBrowserTracingIntegration（路由器）， ], 痕迹采样率：1.0， }); **nuqs 集成：** // src/routes/__root.tsx 从 'nuqs/adapters/tanstack-router' 导入 { NuqsAdapter }；函数根布局（）{ 返回（ <出口/> ）； } **增量迁移（旧版兼容性）：** 有关在迁移期间同时运行两个路由器的模式，请参阅 [references/incremental-migration.md]()。 ## 快速参考 ### 路由文件命名图案|文件|网址 ---|---|--- 索引路线 | `主题/index.tsx` | `/主题` 动态参数 | `主题/$topicName.tsx` | `/主题/:主题名称` 嵌套动态| `topics/$topicName/edit.tsx` | `/主题/:主题名称/编辑` 无路径布局 | `_layout.tsx` | （无 URL 段）包罗万象 | `$.tsx` | `/*` ### 常见 Zod 模式从“@tanstack/zod-adapter”导入{后备，zodValidator}；从 'zod' 导入 { z }； const searchSchema = z.object({ // 可选字符串，默认值未定义选项卡：后备（z.string（）.可选（），未定义）， // 具有默认值的可选数字页面：后备（z.number（）.可选（），1）， // 必需的字符串 id: z.string(), // 具有默认值的枚举排序：后备（z.enum（['asc'，'desc']）.可选（），'asc'）， // 布尔值扩展：后备（z.boolean（）。可选（），假）， }); ### `from` 参数中的尾部斜杠 `from` 参数必须与定义的路由路径完全匹配： // 索引路由（名为index.tsx的文件）包含尾部斜杠： useParams({ from: '/topics/$topicName/' }) // 路由：topics/$topicName/index.tsx // 非索引路由不包含尾部斜杠： useParams({ from: '/topics/$topicName/edit' }) // 路由：topics/$topicName/edit.tsx ### 类型安全导航 // 带参数 <链接到="/topics/$topicName" params={{ topicName: 'my-topic' }}> 查看主题 // 带搜索参数 <链接到=“/主题”搜索= {{页：2，排序：'desc'}}> 第2页 // 程序化导航 const navigation = useNavigate({ from: '/topics/$topicName' }); 导航（{ 至：'/topics/$topicName/edit', 参数：{ 主题名称 }, 搜索：{选项卡：'设置'}， }); ## 清单 ### 预迁移 * 安装依赖项（`@tanstack/react-router`、`@tanstack/router-plugin`、`@tanstack/zod-adapter`） * 配置构建工具插件 * Linter 配置为允许 `$param.tsx` 命名 * 创建`src/routes/`目录 ### 路由迁移 * 使用提供程序和布局创建的 `__root.tsx` * 为根重定向创建的`index.tsx` * 所有路由迁移到基于文件的结构 * 使用 Zod 模式验证的搜索参数 * 为标题/图标添加了“staticData” ### 钩子迁移 * 所有 `useParams` 调用都使用 `from` 参数进行更新 * 所有 `useSearchParams` 替换为 `routeApi.useSearch()` * 使用“from”参数更新所有“useNavigate”调用 * 所有“Link”组件均已验证工作正常 ### 测试 * 创建了 `renderWithFileRoutes` 实用程序 * Vitest 配置了 TanStack Router 插件 * 现有测试已更新以使用新实用程序 ### 集成 * 配置哨兵集成（如果使用） * nuqs 适配器包裹在根布局中（如果使用） ### 清理（完全迁移后） * 删除了 React Router 依赖项 * 删除了旧的路由定义 * 删除了 BrowserRouter 包装 * 删除了 RouterSync 组件 ## 常见陷阱 1. **缺少`from`参数** \- 始终在钩子中指定`from`以确保类型安全 2. **忘记 `fallback()` 包装器** \- 可选搜索参数需要 `fallback(z.string().optional(), undefined)` 3. **尾部斜杠不一致** \- 配置 `trailingSlash: 'never'` 并保持一致 4. **编辑routeTree.gen.ts** \- 从不编辑；它是在文件更改时自动生成的 5. **缺少构建插件** \- 如果没有捆绑器插件，将不会生成路由 6. **异步导航警告** \- `navigate()` 返回 Promise；使用 `void navigator()` 或等待它 7. **使用 `` 进行部分重定向** \- 使用 `beforeLoad` 和 `throw redirect()` 来防止嵌入模式下的导航循环：加载前：() => { 抛出重定向({ to: '/section/$tab', params: { tab: 'default' }, 替换: true }); } 8. **索引路由的“from”参数中的尾部斜杠** \- 索引路由（名为“index.tsx”的文件）需要“from”中的尾部斜杠： // 索引路由：/topics/$topicName/index.tsx useParams({ from: '/topics/$topicName/' }) // ✅ 正确（尾部斜杠） useParams({ from: '/topics/$topicName' }) // ❌ 错误 9. **缺少 HistoryState 扩展** \- 为类型化导航状态扩展 `HistoryState` 接口（参见第 3 阶段） ## 文档 * [TanStack 路由器文档]() * [基于文件的路由]() * [测试基于文件的路由]() * [哨兵集成]() * [nuqs 适配器]()

Tanstack 路由器迁移

包含技能