概述

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

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

要快速开始，请转到下一页。如果您想要更详细的解释，请系好安全带，让我为您详细介绍！

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

那么，为什么您应该选择 TanStack Router 而不是其他路由器？

要回答这个问题，我们需要看看这个领域的其他选择。如果您仔细寻找，有很多选择，但根据我的经验，只有几个值得认真探索：

• Next.js - 被广泛认为是启动新 React 项目的事实标准框架，它专注于性能、工作流程和前沿技术。它的 API 和抽象很强大，但有时可能显得不标准。它在行业中的极快增长和采用导致了功能丰富的体验，但代价是感觉压倒性和有时臃肿。
• Remix / React Router - 基于历史上成功的 React Router 的全栈框架提供了类似强大的开发者和用户体验，其 API 和愿景牢固地基于 Request/Response 等 Web 标准，专注于在 JS 可以运行的任何地方运行。它的许多 API 和抽象设计得很好，并且是不少 TanStack Router API 的灵感来源。话虽如此，它的刚性设计、附加的类型安全以及有时对平台 API 的严格过度遵守可能会让一些开发者想要更多。

这两个框架（及其路由器）都很棒，我可以亲自证明两者都是构建 React 应用程序的非常好的解决方案。我的经验也告诉我，这些解决方案也可以做得更好，特别是在开发者可用的实际路由 API 方面，以使他们的应用程序更快、更容易、更愉快地工作。

此时，选择路由器如此重要以至于它通常与您的框架选择 1 对 1 绑定，这可能并不令人惊讶，因为大多数框架依赖于特定的路由器。

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

TanStack Router 本身在传统意义上不是"框架"，因为它不解决其他一些常见的全栈关注点。但是，TanStack Router 被设计为在与解决打包、部署和服务器端特定功能的其他工具结合使用时可升级为全栈框架。这就是为什么我们目前正在开发 TanStack Start，这是一个建立在 TanStack Router 和 Vite 之上的全栈框架。

要深入了解 TanStack Router 的历史，请随时阅读 TanStack Router 的历史。

TanStack Router 实现了您对其他路由器期望的相同基本功能：

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

它还提供了一些提高标准的新功能：

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

让我们更详细地深入了解其中一些更重要的功能！l!

如今一切都是用"TypeScript"编写的，或者至少提供了覆盖运行时功能的类型定义，但生态系统中实际上在设计 API 时考虑 TypeScript 的包太少了。所以，虽然我很高兴您的路由器能够自动完成选项字段并在这里和那里捕获一些属性/方法拼写错误，但还有更多可以获得的。

• 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 提供了一个与路由器无缝协作的轻量级内置缓存层。这个缓存层松散地基于 TanStack Query，但功能更少，API 表面积更小。像 TanStack Query 一样，合理但强大的默认设置保证您的数据被缓存以供重用，在必要时失效，在不使用时进行垃圾回收。它还提供了一个简单的 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 还有很多事情要做。点击下一个按钮，让我们开始吧！