使用 TanStack Router CLI 安装并配置文件路由File-based Routing【免费下载链接】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本文面向希望在不使用 Vite/Rspack 等受支持打包器插件的前提下、仅凭命令行工具启用 TanStack Router 文件路由File-based Routing的开发者。文章以官方安装指南为主体结合当前仓库中tanstack/router-cli与tanstack/router-generator的源码实现完整讲解tsr generate/tsr watch命令、tsr.config.json的全部配置项、生成文件忽略策略以及仓库内真实 e2e 示例的落地方式。读完本文你将能脱离打包器插件独立用 CLI 完成路由树的生成与持续监听。什么时候应该使用 Router CLITanStack Router 官方安装指南在最开始就给出了一条重要警告只有当你没有使用受支持的打包器bundler时才应该使用 TanStack Router CLI。这是因为 CLI 只支持路由树文件route tree file的生成这一项能力不提供其他任何功能。也就是说如果你使用 Vite、Rspack、Webpack 等受支持打包器应优先使用对应的打包器插件如tanstack/router-vite-plugin插件能提供代码分割auto code-splitting、虚拟文件路由、路由懒加载等完整能力如果你的构建链路无法接入这些插件例如自研构建脚本、非标准打包流程再退而使用tanstack/router-cli通过命令行在构建前生成路由树。从仓库源码看CLI 的核心逻辑极简packages/router-cli/src/index.ts 通过yargs只注册了两个子命令generate与watch二者最终都委托给tanstack/router-generator包的Generator类完成实际的路由树生成这印证了CLI 仅做路由树生成的定位。安装tanstack/router-cli要使用文件路由首先需要安装tanstack/router-cli包React 与 Solid 场景通用本文仓库内同样提供了 Vue 支持详见下文配置部分npm install -D tanstack/router-cli # 或使用 pnpm / yarn / bun按你的包管理器习惯即可安装后包会提供tsr二进制命令。仓库中 packages/router-cli/package.json 的bin字段声明为tsr: bin/tsr.cjsengines要求node 20.19其依赖只有三个tanstack/router-generator路由树生成核心、chokidar文件监听、yargs命令行解析。在package.json中接入 generate 与 watch 脚本安装完成后需要修改package.json的scripts让 CLI 在构建与开发阶段分别执行generate和watch{ scripts: { generate-routes: tsr generate, watch-routes: tsr watch, build: npm run generate-routes ..., dev: npm run watch-routes ... } }tsr generate基于配置一次性生成路由树适合放入build流程tsr watch持续监听配置的目录文件增删改时自动重新生成适合放入dev流程。仓库中的 e2e 示例 e2e/react-router/generator-cli-only/package.json 是这一做法的真实落地它的dev脚本为tsr generate vite --port 3000build脚本为tsr generate vite build tsc --noEmit即先执行 CLI 生成路由树再交给 Vite 构建全程没有使用打包器插件。Solid 用户补充的 tsconfig 配置如果你使用 Solid并且项目基于 TypeScript还需要在tsconfig.json中补充以下编译选项确保 JSX 转换指向 Solid{ compilerOptions: { jsx: preserve, jsxImportSource: solid-js } }配置完成后即可开始使用基于文件路由的 TanStack Router。React 用户无需此额外步骤。tsr命令详解CLI 安装后通过tsr命令暴露以下能力对应源码 packages/router-cli/src/index.ts 中的两个 command。tsr generate根据提供的配置为项目生成路由routes。用法tsr generate其实现位于 packages/router-cli/src/generate.ts先通过getConfig()读取并解析配置然后new Generator({ config, root })实例化生成器并执行generator.run()成功时以退出码 0 结束失败则打印错误并以退出码 1 结束。因此它非常适合作为 CI / 构建流水线中的前置步骤——命令失败会直接导致构建失败从而第一时间暴露路由文件错误。tsr watch持续监听指定目录并在文件变化时按需重新生成路由。用法tsr watch开启文件路由后每当你在开发模式下启动应用TanStack Router 就会监听配置的routesDirectory并在其中任何文件被添加、删除或修改时重新生成路由树。从源码 packages/router-cli/src/watch.ts 可以看清它的工作机制使用chokidar监听配置文件tsr.config.json通过resolveConfigPath定位配置文件就绪或发生变化时重新调用getConfig()读取最新配置实例化Generator并转而监听config.routesDirectory目录目录ready后立即执行一次generator.run()保证启动即生成最新路由树此后监听all事件将add/change/unlink分别映射为create/update/delete类型的文件事件调用generator.run({ path, type })做增量生成。因此watch不仅监听路由目录还会在tsr.config.json本身被修改时自动热重载配置并切换监听目标无需重启进程。忽略生成的 route tree 文件路由树文件由 TanStack Router 自动管理属于生成产物不应被你的 linter 或 formatter 修改。如果项目配置了 ESLint、Prettier 或 Biome建议将生成的路由树文件默认src/routeTree.gen.ts加入忽略列表Prettier在.prettierignore中忽略生成文件ESLint在 ESLint 配置的ignores中忽略生成文件Biome在配置文件如biome.json的files.ignore中忽略生成文件。VSCode 下的特殊处理[!WARNING] 如果你使用 VSCode在重命名一个路由文件后可能会意外弹出打开的路由树文件并显示错误。可以在 VSCode 设置中把该文件标记为只读并建议同时将其从搜索结果与文件监听中排除。推荐配置如下{ files.readonlyInclude: { **/routeTree.gen.ts: true }, files.watcherExclude: { **/routeTree.gen.ts: true }, search.exclude: { **/routeTree.gen.ts: true } }这些设置既可以放在用户级settings.json也可以只针对单个工作区——在项目根目录创建.vscode/settings.json即可。配置说明与默认值使用 Router CLI 进行文件路由时内置了一套合理的默认配置对大多数项目开箱即用。React 与 Solid 的默认配置分别为// React { routesDirectory: ./src/routes, generatedRouteTree: ./src/routeTree.gen.ts, routeFileIgnorePrefix: -, quoteStyle: single, target: react }// Solid { routesDirectory: ./src/routes, generatedRouteTree: ./src/routeTree.gen.ts, routeFileIgnorePrefix: -, quoteStyle: single, target: solid }如果这些默认值满足你的需求无需任何额外配置。需要自定义时在项目根目录创建tsr.config.json即可CLI 通过 packages/router-generator/src/config.ts 的resolveConfigPath定位到./tsr.config.json并读取合并。全部可用配置项以下为完整的配置项说明细节均可在 docs/router/api/file-based-routing.md 与 packages/router-generator/src/config.ts 的configSchema中找到对应实现配置项默认值说明routesDirectory./src/routes路由文件所在目录相对于当前工作目录cwd不可为空generatedRouteTree./src/routeTree.gen.ts生成路由树的输出文件路径相对于 cwd不可为空若disableTypes为true则扩展名变为.jstargetreact生成目标支持react/solid/vuerouteFilePrefix空只有以此前缀开头的文件才会被当作路由文件默认为空即目录下所有文件都参与路由routeFileIgnorePrefix-忽略指定前缀的文件/目录便于在路由目录内内聚存放非路由文件routeFileIgnorePatternundefined以正则表达式忽略特定文件/目录例如.((css\|const).ts)\|test-pageindexTokenindex标识 index 路由文件URL 与父路径完全相同时匹配支持正则routeTokenroute标识 layout 路由文件支持正则quoteStylesingle生成路由树与新路由脚手架时的引号风格single/doublesemicolonsfalse生成文件是否使用分号结尾disableTypesfalse为true时生成的路由树不含类型且输出为.js文件disableLoggingfalse关闭路由生成过程的控制台日志addExtensionsfalse控制生成路由树中 import 路径的扩展名false去除扩展名true保留原扩展名传字符串如js则替换为指定扩展名ESM 下 Node 要求.js时很有用routeTreeFileHeader[/* eslint-disable */, // ts-nocheck, // noinspection JSUnusedGlobalSymbols]预置到生成文件头部的内容routeTreeFileFooter[]追加到生成文件尾部的内容也可传函数enableRouteTreeFormattingtrue是否对生成文件执行格式化大项目可关闭以节省时间autoCodeSplittingfalse自动代码分割仅在使用打包器插件时可用CLI 场景不生效tmpDir.tanstack/tmp原子写入所用临时目录相对路径基于 cwd 解析其次读process.env.TSR_TMP_DIR关于routeFileIgnorePrefix的典型用法默认值-允许你在路由目录内内聚存放非路由文件。例如下面结构中-components目录会被忽略不会参与路由src/routes ├── posts │ ├── -components // Ignored │ │ ├── Post.tsx │ ├── index.tsx │ ├── route.tsx从 packages/router-generator/src/config.ts 的validateConfig可以看到两个硬性校验indexToken与routeToken不能相同routeFileIgnorePrefix不能是下划线_因为_被保留用于表示无路径pathless路由。同时官方 API 参考也警告不要将routeFilePrefix、routeFileIgnorePrefix或routeFileIgnorePattern设置为与文件命名规范中任何 token 相同的值否则可能产生意外行为。使用正则表达式作为indexToken/routeToken除了字面字符串indexToken与routeToken还支持正则。在tsr.config.jsonJSON中使用带regex与可选flags的对象{ routeToken: { regex: [a-z]-layout, flags: i } }在内联配置代码中则直接使用原生RegExp{ routeToken: /[a-z]-layout/i }以[a-z]-layout为例dashboard.main-layout.tsx、posts.protected-layout.tsx、admin.settings-layout.tsx都会被识别为 layout 路由。注意正则是对路由路径最后一段的完整内容进行匹配——dashboard.main-layout.tsx匹配成功而dashboard.my-layout-extra.tsx不匹配。同理indexToken也可用{ regex: [a-z]-page }匹配home-page.tsx、posts.list-page.tsx等 index 路由。若想保留字面段而不被当作 token 解析可用方括号转义例如[home-page].tsx。仓库内的端到端参考实现如果你希望看到一个仅用 CLI、不用打包器插件的完整可运行项目仓库中的 e2e 示例 e2e/react-router/generator-cli-only 是最佳参考。它的 tsr.config.json 只有两行配置{ routesDirectory: ./src/routes, generatedRouteTree: ./src/routeTree.gen.ts }其src/routes目录覆盖了文件路由的各种形态__root.tsx根路由、index.tsxindex 路由、posts.$postId.tsx动态路径参数、posts.index.tsx与posts.route.tsx同一 URL 的多种等价写法、_pathlessLayout.tsx与嵌套的_nested-layout.tsxpathless 布局。通过阅读 src/routes/routeTree.gen.ts 这一生成产物可以直观看到 CLI 如何把上述文件结构编译为类型安全的路由树代码。配套的 tests/app.spec.ts 则验证了各路由在实际浏览器环境中的可访问性。小结TanStack Router CLI 是文件路由在非打包器场景下的官方入口安装tanstack/router-cli、在package.json中串联tsr generate与tsr watch、按需创建tsr.config.json覆盖默认值即可获得与打包器插件一致的路由树生成能力。需要留意的是它只负责生成路由树不具备打包器插件的自动代码分割、虚拟路由等进阶能力同时务必把生成的routeTree.gen.ts加入 linter / formatter 忽略列表并在 VSCode 中将其设为只读避免开发过程中的误改与弹窗干扰。【免费下载链接】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），仅供参考