在 Rspack 与 Rsbuild 中集成 TanStack Router 文件路由tanstack/router-plugin/rspack配置实战【免费下载链接】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本仓库packages/router-plugin等包构成的现代全类型安全路由框架默认依赖 Vite 插件完成文件路由生成与自动代码分割但当项目使用 Rspack 或基于 Rspack 的构建工具 Rsbuild 时需要安装并接入tanstack/router-plugin包并正确挂载其 Rspack 插件入口。本文以官方安装文档 docs/router/installation/with-rspack.md 为主线完整讲解 React 与 Solid 两种框架下的配置方式、生成文件routeTree.gen.ts的忽略策略、默认配置项并结合 rspack.ts、config.ts 等源码与仓库内的可运行示例帮助读者在 Rspack/Rsbuild 工程中零障碍地启用文件路由。一、为什么 Rspack/Rsbuild 需要额外的插件TanStack Router 的文件路由能力分为两个阶段路由树生成扫描src/routes目录根据文件命名约定生成类型安全的路由树文件默认src/routeTree.gen.ts自动代码分割对路由的component、loader等节点做按需拆包并注入框架React/Solid对应的 HMR 运行时代码。这两个阶段分别由 router-generator-plugin.ts 与 router-code-splitter-plugin.ts 负责最后通过 router-composed-plugin.ts 组合成一个对外暴露的插件。由于 Rspack 与 Vite 的插件 API、HMR 协议并不相同官方将同一套核心逻辑用unplugin适配到了各构建工具因此 Rspack/Rsbuild 用户必须使用tanstack/router-plugin包中面向 Rspack 的入口/rspack子路径而不能直接使用 Vite 版插件。从 package.json 可以看出该包通过exports暴露了./vite、./webpack、./esbuild、./rspack等多个入口其中./rspack正是本文的核心。同时rsbuild/core被声明为可选的 peer 依赖1.0.2 || ^2.0.0也就是说只有当你确实在使用 Rsbuild/Rspack 时才需要安装它。二、安装tanstack/router-plugin要使用 Rspack 或 Rsbuild 的文件路由只需将tanstack/router-plugin安装为开发依赖React 与 Solid 使用同一个包无需区分安装npm install -D tanstack/router-plugin # 或 pnpm add -D tanstack/router-plugin # 或 yarn add -D tanstack/router-plugin # 或 bun add -d tanstack/router-plugin安装完成后需要在你的 Rspack/Rsbuild 配置中添加该插件。注意本包要求 Node.js20.19见 package.json 的engines字段请确保运行环境满足要求。三、React 项目的 Rsbuild 配置以官方 React 示例 examples/react/quickstart-rspack-file-based 为例在rsbuild.config.ts中同时启用rsbuild/plugin-react与tanstackRouter插件import { defineConfig } from rsbuild/core import { pluginReact } from rsbuild/plugin-react import { tanstackRouter } from tanstack/router-plugin/rspack export default defineConfig({ plugins: [pluginReact()], tools: { rspack: { plugins: [ tanstackRouter({ target: react, autoCodeSplitting: true, }), ], }, }, })要点说明tanstackRouter必须从tanstack/router-plugin/rspack导入这是 Rspack 专用入口rspack.ts 中将其封装为TanStackRouterRspacktarget: react明确当前工程面向 ReactautoCodeSplitting: true启用自动代码分割它等价于在代码中调用route.lazy等手动拆分方案的自动化版本插件需要放在tools.rspack.plugins数组内与pluginReact()插件在plugins数组分工不同前者处理 React JSX 编译后者负责 TanStack Router 的路由生成与拆包。仓库中的 rsbuild.config.ts 与上文配置完全一致可直接作为模板使用。3.1 配套依赖与运行脚本参考示例的 package.json一个最小可运行的 React Rspack 工程还需要{ dependencies: { tanstack/react-router: ^1.170.35, tanstack/react-router-devtools: ^1.167.1, react: ^19.0.0, react-dom: ^19.0.0 }, devDependencies: { rsbuild/core: ^2.1.0, rsbuild/plugin-react: ^2.0.0, tanstack/router-plugin: ^1.168.37, typescript: ^7.0.2 }, scripts: { dev: rsbuild dev --port 3000, build: rsbuild build tsc --noEmit, preview: rsbuild preview } }随后运行npm run dev默认 3000 端口即可启动开发服务器npm run build会先构建再执行类型检查tsc --noEmit用来验证生成的routeTree.gen.ts与业务代码的类型正确性。3.2 路由文件长什么样示例的 src/routes/__root.tsx 展示了文件路由下的根路由写法——通过createRootRoute创建根路由使用Link声明式导航、Outlet渲染子路由并挂载TanStackRouterDevtools便于调试import * as React from react import { Link, Outlet, createRootRoute } from tanstack/react-router import { TanStackRouterDevtools } from tanstack/react-router-devtools export const Route createRootRoute({ component: RootComponent, }) function RootComponent() { return ( div classNamep-2 flex gap-2 text-lg Link to/ activeProps{{ className: font-bold }} activeOptions{{ exact: true }} Home /Link{ } Link to/about activeProps{{ className: font-bold }} About /Link /div hr / Outlet / TanStackRouterDevtools positionbottom-right / / ) }四、Solid 项目的 Rsbuild 配置Solid 需要先经过 Babel 转换因为 Solid 使用编译期的 signal 语法因此配置略有不同。官方 Solid 示例 examples/solid/quickstart-rspack-file-based/rsbuild.config.ts 的完整配置如下import { defineConfig } from rsbuild/core import { pluginBabel } from rsbuild/plugin-babel import { pluginSolid } from rsbuild/plugin-solid import { tanstackRouter } from tanstack/router-plugin/rspack export default defineConfig({ plugins: [ pluginBabel({ include: /\.(?:jsx|tsx)$/, }), pluginSolid(), ], tools: { rspack: { plugins: [tanstackRouter({ target: solid, autoCodeSplitting: true })], }, }, })与 React 配置的区别增加了rsbuild/plugin-babel并用include: /\.(?:jsx|tsx)$/限定仅对 JSX/TSX 文件做 Babel 转译避免误伤其他文件影响构建性能增加了rsbuild/plugin-solid处理 Solid 的 JSX 编译tanstackRouter的target改为solid自动代码分割依然开启。五、快速上手克隆官方示例除了手写配置也可以直接克隆仓库中的官方快速开始示例Reactexamples/react/quickstart-rspack-file-basedSolidexamples/solid/quickstart-rspack-file-based克隆后在对应目录安装依赖、运行npm run dev即可得到一个包含/与/about两个页面的最小文件路由应用。这两个示例是验证本插件配置是否生效的最快途径也常被用作新项目脚手架。六、忽略生成的routeTree.gen.ts路由树文件由插件自动生成并持续维护因此不应被你的 linter 或 formatter 修改。如果工程配置了代码检查与格式化工具建议将生成文件加入忽略名单Prettier在.prettierignore中追加routeTree.gen.ts对应路径模式如src/routeTree.gen.tsESLint在 ESLint 配置的ignorePatterns中加入该文件路径Biome在biome.json的files.ignore中配置忽略项。[!WARNING] 如果你使用 VSCode重命名路由后可能会遇到routeTree.gen.ts意外打开并显示错误的情况。可以通过 VSCode 设置将该文件标记为只读并建议同时将其从搜索结果与文件监听watcher中排除。官方推荐的settings.json如下{ files.readonlyInclude: { **/routeTree.gen.ts: true }, files.watcherExclude: { **/routeTree.gen.ts: true }, search.exclude: { **/routeTree.gen.ts: true } }这三项设置的作用分别是files.readonlyInclude把routeTree.gen.ts标记为只读防止意外编辑files.watcherExclude将该文件移出文件监听避免与插件自身的监听互相干扰、触发不必要的重载search.exclude让全局搜索跳过该文件减少噪音。你可以在用户级设置中全局生效也可以仅在单个工作区生效——在项目根目录创建.vscode/settings.json写入以上内容即可。七、默认配置与自定义配置在 Rspack或 Rsbuild下使用文件路由时插件带有对大多数项目足够友好的合理默认值与 Vite 版一致{ routesDirectory: ./src/routes, generatedRouteTree: ./src/routeTree.gen.ts, routeFileIgnorePrefix: -, quoteStyle: single }各默认项的含义配置项默认值说明routesDirectory./src/routes路由文件所在目录相对于当前工作目录cwd必填且不能为空generatedRouteTree./src/routeTree.gen.ts生成的路由树文件保存路径相对于 cwd必填且不能为空若disableTypes为true则输出为.js后缀routeFileIgnorePrefix-以该前缀命名的文件/目录会被忽略不参与路由解析用于在路由目录中放置非路由的共置文件如posts/-components/Post.tsxquoteStylesingle生成代码中字符串引号风格single/double如果这些默认值符合你的工程无需任何额外配置。需要自定义时直接修改传给tanstackRouter()函数的配置对象即可例如tanstackRouter({ target: react, routesDirectory: ./app/routes, generatedRouteTree: ./app/routeTree.gen.ts, quoteStyle: double, autoCodeSplitting: true, })完整的配置项清单routesDirectory、generatedRouteTree、virtualRouteConfig、routeFilePrefix、routeFileIgnorePrefix、routeFileIgnorePattern、indexToken、routeToken、quoteStyle、semicolons、autoCodeSplitting、disableTypes、addExtensions、disableLogging、routeTreeFileHeader、routeTreeFileFooter、enableRouteTreeFormatting、tmpDir以及各参数的行为与正则写法请参见 File-based Routing API Reference。注意该文档中有明确警告不要将routeFilePrefix、routeFileIgnorePrefix或routeFileIgnorePattern设置为与文件命名约定指南中的任何 token 相同否则可能引发意外行为。八、源码级解析Rspack 插件入口与 HMR 适配8.1rspack.ts组合插件与导出Rspack 入口位于 packages/router-plugin/src/rspack.ts核心逻辑如下tanstackRouter即TanStackRouterRspack通过unplugin的createRspackPlugin包装 router-composed-plugin.ts 中的unpluginRouterComposedFactory对外表现为一个标准的 Rspack 插件同时单独导出TanStackRouterGeneratorRspack仅路由树生成与TanStackRouterCodeSplitterRspack仅代码分割供需要拆分职责的高级场景使用导出configSchemazod 校验模式与Config类型方便用户在自己的配置里做类型对齐。值得注意的实现细节是withWebpackHmrStyleRspack 使用与 webpack 兼容的module.hot/import.meta.webpackHotHMR 协议因此该函数会强制将plugin.hmr.style覆盖为webpack无论用户传什么或不传。这样代码分割插件 router-code-splitter-plugin.ts 生成的 HMR 代码就是module.hot风格的 accept/dispose而非 Vite 的回调式变体——这也是为什么 Rspack 场景不能直接复用 Vite 插件的原因之一。8.2config.ts配置 schema 与代码分割选项packages/router-plugin/src/core/config.ts 定义了插件配置的类型约束基于 zodconfigSchema在路由生成器配置之上扩展了enableRouteGeneration是否启用路由生成、codeSplittingOptions与plugin对象plugin.hmr.style仅允许vite | webpack两个取值rspack.ts正是通过该字段完成 HMR 风格切换codeSplittingOptions包含四个子项splitBehavior按routeId编程式控制每个路由的拆包行为defaultBehavior全局默认拆包分组默认值为[[component], [pendingComponent], [errorComponent], [notFoundComponent]]即把组件、pending、error、notFound 四类节点分别拆成独立 chunkdeleteNodes需要从路由中删除的节点addHmr是否注入 HMR 代码默认true。这解释了autoCodeSplitting: true的底层语义它让插件按defaultBehavior自动为每个路由拆分出component、pendingComponent、errorComponent、notFoundComponent对应的代码块从而在不需要手写route.lazy的情况下获得按路由粒度加载的体验。九、与其他构建工具的入口对比本仓库的安装文档提供了多份针对不同构建工具的指南可对照阅读with-vite.mdVite 场景使用tanstack/router-plugin/vitewith-webpack.mdwebpack 场景使用tanstack/router-plugin/webpackwith-esbuild.mdesbuild 场景manual.md不使用构建工具插件时的手动接入方式手动维护路由树或使用 CLIwith-router-cli.md通过tanstack/router-cli独立生成路由树。其中 Rspack 与 webpack 共享同一套 HMR 风格webpack因此 webpack-adapter.ts 的 HMR 适配逻辑对两者同样适用而从 select-adapter.ts 可以进一步看到插件是如何根据plugin.hmr.style在 Vite 适配器与 webpack 适配器之间做选择的。十、小结在 Rspack/Rsbuild 工程中使用 TanStack Router 文件路由只需三步安装tanstack/router-plugin开发依赖 → 在rsbuild.config.ts的tools.rspack.plugins中注册tanstackRouter({ target: react | solid, autoCodeSplitting: true })→ 将自动生成的routeTree.gen.ts加入 linter/formatter 忽略名单VSCode 用户可配合只读与搜索排除设置。底层实现上tanstack/router-plugin/rspack入口通过unplugin将路由树生成与自动代码分割组合为标准 Rspack 插件并自动把 HMR 风格强制为 webpack 兼容模式确保在 Rspack 下获得与 Vite 一致的路由开发体验。如需深入探索可直接阅读 rspack.ts、config.ts 的源码或直接运行仓库中的 React 示例 与 Solid 示例 验证效果。【免费下载链接】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），仅供参考