概述

TanStack Router 是一个用于构建 React 和 Solid 应用程序的路由库。它的一些特性包括：

• 100% 推断的 TypeScript 支持
• 类型安全的导航
• 嵌套路由和布局路由（支持无路径布局）
• 内置路由加载器，支持 SWR 缓存
• 专为客户端数据缓存设计（TanStack Query、SWR 等）
• 自动路由预取
• 异步路由元素和错误边界
• 基于文件的路由生成
• 类型安全的 JSON 优先搜索参数状态管理 API
• 路径和搜索参数模式验证
• 搜索参数导航 API
• 自定义搜索参数解析器/序列化器支持
• 搜索参数中间件
• 路由匹配/加载中间件

要快速入门，请前往下一页。如果需要更详细的解释，请坐稳，我将带您快速了解！

"路线分叉"

使用路由构建应用程序被广泛认为是一种必备技能，通常也是您在技术栈中做出的第一个选择之一。

这是否意味着 TanStack Router 是一个框架？

TanStack Router 本身并不是传统意义上的“框架”，因为它不涉及其他一些常见的全栈开发问题。然而，TanStack Router 被设计成在与打包、部署和服务器端特定功能等其他工具结合使用时，可以升级为一个全栈框架。这就是为什么我们目前正在开发 TanStack Start，这是一个基于 TanStack Router 和 Vite 构建的全栈框架。

有关 TanStack Router 历史的更深入了解，请随时阅读 TanStack Router 的起源故事。

为什么选择 TanStack Router？

TanStack Router 满足了您对其他路由所期待的相同基本期望。

• 嵌套路由、布局路由、分组路由
• 基于文件的路由
• 并行数据加载
• 预取
• URL 路径参数
• 错误边界和处理
• SSR
• 路由遮罩

它还带来了一些提升标准的新功能。

• 100% 推断的 TypeScript 支持
• 类型安全的导航
• 加载器的内置 SWR 缓存
• 专为客户端数据缓存设计（TanStack Query、SWR 等）
• 类型安全的 JSON 优先搜索参数状态管理 API
• 路径和搜索参数模式验证
• 搜索参数导航 API
• 自定义搜索参数解析器/序列化器支持
• 搜索参数中间件
• 继承的路由上下文
• 混合文件和代码路由

让我们更详细地探讨其中一些更重要的特性！

100% 推断式 TypeScript 支持

如今，一切都“用 TypeScript 编写”，或者至少提供覆盖在运行时功能上的类型定义，但生态系统中真正将 TypeScript 放在 API 设计核心的包却寥寥无几。因此，虽然我很高兴您的路由器能自动补全您的选项字段并捕获一些属性/方法拼写错误，但还有更多可以做的。

• TanStack Router 在任何时候都能完全了解您代码中的所有路由及其配置。这包括路径、路径参数、搜索参数、上下文以及您提供的任何其他配置。最终，这意味着您可以使用 100% 的类型安全导航到您应用中的任何路由，并确信您的链接或导航调用将成功。
• TanStack Router 提供无损类型推断。它使用无数个泛型类型参数来强制执行和传播您提供的任何类型信息，贯穿其 API 的其余部分，并最终在您的应用程序中。没有其他路由器能提供这种级别的类型安全和开发人员信心。

这一切对您意味着什么？

• 通过自动补全和类型提示实现更快的特性开发
• 更安全、更快速的重构
• 确保代码按预期工作的信心

一流的搜索参数

搜索参数通常是事后才考虑的，被视为一个字符串（或字符串数组）的黑盒，您可以解析和更新它们，但不能做太多其他事情。现有的解决方案也不支持类型安全，这增加了处理它们的谨慎性。即使是“最现代”的框架和路由器，也让您自己弄清楚如何管理这种状态。有时它们会为您将搜索字符串解析为对象，有时您需要使用 URLSearchParams 自己处理。

让我们退一步想想，搜索参数是您整个应用程序中最强大的状态管理器。它们是全局的、可序列化的、可书签化和可共享的，这使得它们成为存储任何需要持久化页面刷新或社交分享的状态的理想位置。

为了承担这项责任，搜索参数在 TanStack Router 中是第一公民。虽然仍然基于标准的 URLSearchParams，但 TanStack Router 使用强大的解析器/序列化器来管理搜索参数中更深、更复杂的数据结构，同时保持它们类型安全且易于使用。

这就像在 URL 中拥有 useState！

搜索参数是：

• 自动解析和序列化为 JSON
• 经过验证和类型化
• 从父路由继承
• 可在加载器、组件和 hook 中访问
• 通过 useSearch hook、Link、navigate 和 router.navigate API 轻松修改
• 可通过自定义搜索过滤器和中间件进行自定义
• 通过精细的搜索参数选择器进行订阅，以实现高效的重新渲染

一旦您开始使用 TanStack Router 的搜索参数，您就会想知道以前是如何没有它们而生存下来的。

内置缓存和友好的数据加载

数据加载是任何应用程序的关键部分，虽然大多数现有路由器都提供某种形式的关键数据加载 API，但在缓存和数据生命周期管理方面，它们往往做得不够。现有解决方案存在一些常见问题：

• 完全没有缓存。数据始终是新鲜的，但用户却不得不一遍又一遍地等待频繁访问的数据加载。
• 过度激进的缓存。数据缓存时间过长，导致数据陈旧，用户体验不佳。
• 粗暴的失效策略和 API。数据可能过于频繁地失效，导致不必要的网络请求和资源浪费，或者您可能对何时失效没有任何精细控制。

TanStack Router 通过缓存和数据加载的“两管齐下”方法来解决这些问题。

内置缓存

TanStack Router 提供了一个轻量级的内置缓存层，该缓存层与 Router 无缝协作。该缓存层松散地基于 TanStack Query，但功能更少，API 表面积也小得多。与 TanStack Query 一样，合理的但强大的默认设置保证您的数据被缓存以供重用，在必要时失效，并在不再使用时进行垃圾回收。它还提供了一个简单的 API，可在需要时手动使缓存失效。

灵活且强大的数据生命周期 API

TanStack Router 在设计上具有灵活且强大的数据加载 API，可以更轻松地与现有的数据获取库（如 TanStack Query、SWR、Apollo、Relay，甚至您自己的自定义数据获取解决方案）集成。像 context、beforeLoad、loaderDeps 和 loader 这样的可配置 API 协同工作，使定义声明式数据依赖、预取数据以及轻松管理外部数据源的生命周期变得容易。

继承的路由上下文

TanStack Router 的 router 和 route context 是一个强大的功能，它允许您定义特定于路由的上下文，然后由所有子路由继承。甚至 router 和根路由本身也可以提供上下文。上下文可以同步和异步构建，并可用于在路由和路由配置之间共享数据、配置或函数。这在以下场景中尤其有用：

• 身份验证和授权
• 混合 SSR/CSR 数据获取和预加载
• 主题
• 单例和全局实用程序
• 在预加载、加载和渲染阶段进行柯里化或部分应用程序

此外，如果路由上下文不是类型安全的，那它又算什么呢？TanStack Router 的路由上下文是完全类型安全的，并且以零成本为您推断。

基于文件和/或代码的路由

TanStack Router 同时支持基于文件和基于代码的路由。这种灵活性使您可以选择最适合您项目需求的方案。

TanStack Router 的文件路由方法具有独特的面向用户性。路由配置由 Vite 插件或 TanStack Router CLI 为您生成，并将生成的代码的使用留给您！这意味着即使您使用文件路由，也始终完全掌控您的路由和路由器。

致谢

TanStack Router 在许多其他开源项目推广的概念和模式的基础上进行构建，包括：

• TRPC
• Remix
• Chicane
• Next.js

我们认识到它们开发所付出的投资、风险和研究，但很高兴能将它们设定的标准推向更高。

我们开始吧！

概述够了，TanStack Router 还有很多东西可以做。点击下一页按钮，我们开始吧！