TanStack Router 快速上手：基于 code-based 路由的最小示例与核心配置解析

TanStack Router 快速上手基于 code-based 路由的最小示例与核心配置解析【免费下载链接】router A client-first, server-capable, fully type-safe router and full-stack framework for the web (React and more).项目地址: https://gitcode.com/GitHub_Trending/ro/routerTanStack Router 是一个 client-first、服务端能力完善、全类型安全的 Web 路由与全栈框架。本文以仓库中的 quickstart 示例 为绝对主线完整复现其脚手架方式、依赖清单、路由树搭建流程与构建命令并深入main.tsx源码逐一讲解根路由、子路由、RouterProvider、预加载与滚动恢复等关键配置同时结合tanstack/router-core与官方文档给出底层原理与扩展建议。读完本文你将能在 5 分钟内跑起一个最小可用的 TanStack Router 应用并具备迁移到文件路由、加载器、代码分割等进阶模式的能力。一、示例定位最小可运行的入门项目本仓库examples/react/quickstart是一个刻意保持精简的示例其 README 明确指出它用于演示以下四个目标快速完成 TanStack Router 的初始化安装基础的路由配置code-based 方式简单的页面间导航完整的启动到生产构建流程。整个示例的源码规模非常小入口文件仅 src/main.tsx 一个、package.json 一份、外加 Vite 的 index.html、vite.config.js 与 tsconfig.json。正因为代码量小它非常适合作为学习 TanStack Router 路由对象模型的第一份真实可运行代码。注意本示例采用的是「code-based 路由配置」在代码中通过createRoute显式声明路由与仓库中大量使用src/routes目录约定的 file-based 示例如 basic-file-based是两种不同的路由组织方式二者在 TanStack Router 中完全等价、可混合使用。二、环境准备与依赖清单1. 通过 gitpick 基于示例创建新项目README 推荐使用gitpick直接以本示例为模板创建新项目npx gitpick TanStack/router/tree/main/examples/react/quickstart quickstart如果希望由官方 CLI 引导式地创建全新项目可交互选择 file-based / code-based、TypeScript、Tailwind、Git 初始化等选项可以改用npx tanstack/cli create --router-only相关交互式选项的细节可参考官方文档 quick-start。2. 安装依赖与常用命令进入项目目录后安装依赖并启动开发服务器pnpm install pnpm dev # 等价于 vite --port 3000生产构建与本地预览pnpm build # 等价于 vite build tsc --noEmit pnpm preview # 等价于 vite preview3. 依赖清单解读查看 package.json 可以看到本示例的依赖组合依赖版本区间作用tanstack/react-router^1.170.35路由核心React 适配层tanstack/react-router-devtools^1.167.1浏览器 DevTools 面板组件react/react-dom^19.0.0React 运行时tailwindcss/tailwindcss/vite^4.2.2样式方案本示例用 Tailwind v4 的 Vite 插件形式vite^8.0.14开发与构建工具链vitejs/plugin-react^6.0.1Vite 的 React 支持插件其中值得注意的两点Router 与 Devtools 分开安装tanstack/react-router-devtools是独立的开发期依赖生产构建时不会随业务代码打包这与 basic 示例 的依赖策略一致。Tailwind v4 以 Vite 插件接入vite.config.js中同时注册了tailwindcss()与react()两个插件样式入口则是 src/styles.css 中的import tailwindcss无需额外的 PostCSS 配置文件。三、代码逐行解析从路由树到应用挂载整个应用的核心逻辑全部位于 src/main.tsx它清晰地展示了 TanStack Router 五步走的标准用法创建根路由createRootRoute创建子路由createRoute并挂到父路由组装路由树addChildren创建 Router 实例createRouter通过RouterProvider渲染并挂载应用。1. 创建根路由与全局布局const rootRoute createRootRoute({ component: () ( div classNamep-2 flex gap-2 Link to/ className[.active]:font-bold Home /Link{ } Link to/about className[.active]:font-bold About /Link /div hr / Outlet / TanStackRouterDevtools / / ), })根路由承担三个职责全局导航栏两个Link声明式地指向/与/about。注意className[.active]:font-bold是 Tailwind 的任意变体写法它让当前激活的链接自动加粗——TanStack Router 的Link在匹配到目标路由时会自动添加active类。Outlet /插槽子路由的组件会渲染到此处这是所有嵌套布局的通用模式。DevToolsTanStackRouterDevtools /挂在整个应用的根部开发时会在页面角落显示一个可展开的调试面板。createRootRoute是路由树的根节点仓库中 basic 示例 还展示了根路由可以额外配置notFoundComponent未匹配路由时的 404 页面可作为后续扩展点。2. 创建子路由const indexRoute createRoute({ getParentRoute: () rootRoute, path: /, component: function Index() { return ( div classNamep-2 h3Welcome Home!/h3 /div ) }, }) const aboutRoute createRoute({ getParentRoute: () rootRoute, path: /about, component: function About() { return div classNamep-2Hello from About!/div }, })每个子路由都必须通过getParentRoute指明父路由并声明自己的path。这里有两个关键约定path: /的路由是索引路由index route渲染在父路由的索引位置path: /about是普通路径路由访问/#/about时命中。在更复杂的示例中createRoute还支持loader进入路由前的数据加载例如 basic 示例 的postsLayoutRoute用loader: () fetchPosts()预取文章列表、errorComponent路由级错误边界、validateSearch查询参数校验等选项后续可按需添加。3. 组装路由树const routeTree rootRoute.addChildren([indexRoute, aboutRoute])addChildren把子路由挂到根路由上形成一棵树。当出现更深层的嵌套时如 basic 示例写法为parentRoute.addChildren([...])的递归组合结构一目了然。4. 创建 Router 实例并配置预加载与滚动恢复const router createRouter({ routeTree, defaultPreload: intent, scrollRestoration: true, })这是示例中最重要的两个全局配置下面分别展开。defaultPreload基于「意图」的预加载defaultPreload: intent表示当用户将鼠标悬停hover在Link上或发生 touchstart 事件时就提前加载目标路由的依赖包括懒加载的代码块和 loader 数据让点击后的页面几乎瞬间呈现。官方文档 Preloading 定义了四种取值取值触发时机适用场景false不预加载资源敏感型应用intenthover / touchstart 事件用户最可能点击的下一条路由推荐默认viewport通过 Intersection Observer 进入视口折叠线以下或屏幕外的链接renderLink一渲染即加载总是需要立即可用的路由从源码看defaultPreload的类型定义位于 packages/router-core/src/router.ts#L232同文件还提供了三个配套调优项defaultPreloadDelay触发预加载前的延迟毫秒数默认值为 50见 router.ts#L1183用于避免鼠标快速划过链接时的无效预加载defaultPreloadIntentProximity判定「接近」链接的距离阈值router.ts#L249defaultPreloadStaleTime/defaultPreloadGcTime预加载数据在内存缓存中的新鲜期默认 30 秒与未使用保留期默认 5 分钟详见官方文档 Preloading 的「How long does preloaded data stay in memory」一节。如果你希望对预加载、缓存与回收做更精细的控制官方文档建议引入 TanStack Query 之类的外部缓存库。scrollRestoration滚动位置恢复scrollRestoration: true让路由在浏览器前进/后退时自动恢复到上一次的滚动位置这是现代 SPA 路由的基本体验要求。源码中该选项的类型声明位于 packages/router-core/src/router.ts#L483还可配合scrollRestorationBehavior指定滚动行为auto/smooth见 router.ts#L498。5. 类型注册让全应用获得类型安全declare module tanstack/react-router { interface Register { router: typeof router } }这是 TanStack Router 类型安全体系的关键一环通过 TypeScript 模块增强module augmentation把当前router实例的类型注册进tanstack/react-router模块此后Link的to、useParams、useLoaderData等 API 都会获得基于真实路由树的精确类型推导——路径写错会在编译期直接报错。6. 挂载应用const rootElement document.getElementById(app)! if (!rootElement.innerHTML) { const root ReactDOM.createRoot(rootElement) root.render( StrictMode RouterProvider router{router} / /StrictMode, ) }这里的挂载逻辑与 index.html 中的div idapp/div对应RouterProvider接收前面创建的router实例是应用的入口组件if (!rootElement.innerHTML)是一个常见的水合保护写法仅在容器为空时才执行客户端渲染为将来接入 SSR / 服务端渲染预留了空间若服务端已渲染内容则跳过重复渲染StrictMode由 React 19 提供用于在开发期暴露潜在副作用。四、构建与类型检查README 中pnpm build展开后是vite build tsc --noEmit即vite build用 Vite 打包生产产物tsc --noEmit用 TypeScript 做全量类型检查不输出文件确保类型安全体系真正生效——这是 TanStack Router 类型驱动开发理念的落地保证。示例的 tsconfig.json 开启了strict严格模式、jsx: react-jsx以及 DOM 相关的 lib没有额外引入 path alias 等复杂配置保持最小化。五、从 Quickstart 走向实战扩展路线以本示例为地基仓库提供了大量可直接对照学习的进阶示例code-based 进阶basic 展示 loader、404 页面、pathless layout、路由级错误组件与嵌套路由file-based 路由quickstart-file-based 展示基于src/routes文件约定的写法这也是官方文档 quick-start 推荐的默认方案数据请求集成basic-react-query 展示与 TanStack Query 的配合SSR / 全栈start-basic 展示 TanStack Start 全栈框架下的使用方式。无论选择哪条路线本示例中「根路由 → 子路由 → 路由树 → Router 实例 → RouterProvider」的五步骨架以及defaultPreload、scrollRestoration、类型注册这三个核心配置都是贯穿始终的通用基础。总结examples/react/quickstart用 74 行main.tsx浓缩了 TanStack Router 的全部核心心智模型createRootRoute定义全局布局与Outlet /插槽createRoute声明路径与组件addChildren组装路由树createRouter注入预加载与滚动恢复策略declare module注册类型最后由RouterProvider完成渲染。把这份最小骨架跑通之后再配合 router-core 源码 理解defaultPreload等选项的底层语义你就能平滑地迁移到 loader、文件路由、代码分割与 SSR 等全部高级能力。【免费下载链接】router A client-first, server-capable, fully type-safe router and full-stack framework for the web (React and more).项目地址: https://gitcode.com/GitHub_Trending/ro/router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考