概述

TanStack Router 是一个用于构建 React 和 Solid 应用程序的路由器。它的一些功能包括

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

要快速开始，请前往下一页。如需更详细的解释，请系好安全带，让我带您快速了解！

“路由中的分叉”

使用路由器构建应用程序被广泛认为是必不可少的，并且通常是您在技术堆栈中做出的首批选择之一。

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

TanStack Router 本身并不是传统意义上的“框架”，因为它没有解决其他一些常见的全栈问题。然而，TanStack Router 被设计为可以升级为全栈框架，当与其他工具（如打包、部署和服务器端特定功能）结合使用时。这就是为什么我们目前正在开发 TanStack Start，一个基于 TanStack Router 和 Nitro、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
• 经过验证和类型化
• 从父路由继承
• 可在加载器、组件和钩子中访问
• 使用 useSearch 钩子、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 甚至您自己的自定义数据获取解决方案）集成。可配置的 API，如 context、beforeLoad、loaderDeps 和 loader 协同工作，使您可以轻松定义声明式数据依赖项、预取数据以及轻松管理外部数据源的生命周期。

继承的路由上下文

TanStack Router 的路由器和路由上下文是一项强大的功能，允许您定义特定于路由的上下文，然后该上下文由所有子路由继承。即使是路由器和根路由本身也可以提供上下文。上下文可以同步和异步构建，并且可以用于在路由和路由配置之间共享数据、配置甚至函数。这对于以下场景特别有用，例如

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

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

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

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

TanStack Router 的基于文件的路由方法是独特的用户友好的。路由配置由 Vite 插件或 TanStack Router CLI 为您生成，让您可以自行决定如何使用生成的代码！这意味着您始终可以完全控制您的路由和路由器，即使您使用基于文件的路由。

致谢

TanStack Router 构建在许多其他 OSS 项目推广的概念和模式之上，包括

• TRPC
• Remix
• Chicane
• Next.js

我们承认投入到其开发中的投资、风险和研究，但很高兴将他们设定的标准推向更高的高度。

开始吧！

概述就足够了，TanStack Router 还有很多事情要做。点击下一个按钮，让我们开始吧！