TanStack Solid Router 大型文件式路由large-file-based示例剖析用规模化路由诊断 TypeScript 性能瓶颈【免费下载链接】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本文以仓库中 examples/solid/large-file-based 示例为线索完整拆解如何在 Solid TanStack Solid Router 项目中程序化生成上百条基于文件的路由并通过tsc --extendedDiagnostics对 TypeScript 类型检查性能做量化诊断。读完本文你将掌握路由规模爆炸场景下的复现方法论、生成脚本的构造模式以及解读类型检查诊断输出的具体姿势可直接迁移到自己的路由项目性能排查中。一、示例定位为什么需要一个大型文件式路由项目TanStack Router 的核心卖点之一是文件式路由file-based routing下天然的类型安全路由树由 router-plugin 在构建期从src/routes目录自动生成本示例产物为src/routeTree.gen.ts随后每个createFileRoute(/xxx)都会与全局Register接口联动让Link的to、params、search参数在编译期被严格约束。但这种类型安全是有成本的路由数量越多TypeScript 需要推理的联合类型、字面量类型与泛型实例化就越复杂IDE 补全和tsc检查会随之变慢。正如示例 README.md 所声明的本示例的唯一目的就是This example generates a large amount file based routes to diagnose typescript performance issues即生成大量基于文件的路由用于诊断 TypeScript 性能问题。它不演示任何业务功能而是充当一个可复现、可量化的压力测试台——路由规模从几十条放大到数百条时类型检查耗时如何变化、哪些路由形态绝对路径 / 相对路径 / search 参数 / path 参数对类型系统压力最大。因此本文后续所有命令与代码都服务于同一个目标把路由规模做上去把类型检查的时间与诊断数据测出来。二、快速上手四条命令跑通整个诊断流程README 给出了完整的最小操作序列需 Node.js pnpm 环境仓库为 pnpm workspace建议在示例目录内执行# 1. 安装依赖solid-router、router-plugin、solid-query、zod、tailwind 等 pnpm install # 2. 生成路由程序化创建数百个基于文件的路由源文件 pnpm gen # 3. 构建并更新路由树vite build tsc --noEmit pnpm build # 4. 类型检查并输出诊断信息tsc --extendedDiagnostics pnpm test:types各命令在 package.json 中的真实定义如下{ scripts: { dev: vite --port 3000, build: vite build tsc --noEmit, preview: vite preview, start: vite, gen: node ./src/createRoutes.mjs, test:types: tsc --extendedDiagnostics } }需要注意几个关键点pnpm gen是入口它通过node ./src/createRoutes.mjs直接运行 Node 脚本把少量模板路由批量复制并改写生成数百个真实路由文件。这一步必须在pnpm build之前执行否则路由树中只有模板路由。pnpm build包含两步先vite build此时tanstackRouter插件扫描src/routes并生成routeTree.gen.ts再tsc --noEmit做常规类型检查。pnpm test:types是诊断核心tsc --extendedDiagnostics会输出每个编译阶段如Symbols、Types、Instantiations、Memory used等的统计是量化类型检查开销的第一手数据。该示例的依赖里特意使用了TypeScript 6/7 预览版见下文依赖解读说明这是一个面向未来类型系统性能的前瞻性诊断项目。三、依赖解读用 TypeScript 6/7 做前瞻性性能测试package.json 中除了常规的框架依赖最值得注意的是devDependencies对 TypeScript 的非常规组合{ dependencies: { tailwindcss/vite: ^4.2.2, tanstack/router-plugin: ^1.168.37, tanstack/solid-query: ^5.90.9, tanstack/solid-router: ^1.170.33, tanstack/solid-router-devtools: ^1.167.1, redaxios: ^0.5.1, solid-js: ^1.9.10, tailwindcss: ^4.2.2, zod: ^4.4.3 }, devDependencies: { typescript/native: npm:typescript^7.0.2, typescript: npm:typescript/typescript6^6.0.2, vite: ^8.0.14, vite-plugin-solid: ^2.11.11 } }从依赖可以推断本示例的定位typescript被替换为typescript/typescript6即 TypeScript 6.0 预览包typescript/native指向 TypeScript 7基于原生实现的新编译器路线。这是目前 TypeScript 团队在性能方向上的两个主要实验分支本示例刻意使用它们来检验大规模路由在下一代编译器下的表现。业务侧依赖组合完整tanstack/solid-router提供路由核心tanstack/router-plugin提供 Vite 文件式路由插件tanstack/solid-query提供数据加载路由 loader 中使用queryClient.ensureQueryDatazod用于 search 参数校验 schemasolid-jsvite-plugin-solid提供 Solid 运行时。构建工具为Vite 8预览版与 TypeScript 6/7 一样属于前沿工具链组合。如果你只想复现路由多导致类型慢这个现象把 TypeScript 换回稳定版如 5.x同样成立本示例选择 6/7 是为了同时观察未来编译器对这类泛型密集型代码的优化效果。从源码结构看这属于项目作者主动选型的实验性配置读者按需取舍即可。四、生成脚本剖析如何把 6 个模板变成 400 条路由整个放大路由规模的秘密都藏在 src/createRoutes.mjs 这一个脚本里。它的思路非常朴素读模板 → 字符串替换 → 批量写文件。脚本核心逻辑import { readFile, writeFile, mkdir } from fs/promises import { existsSync } from fs const length 100 // 每个维度的生成数量 const main async () { // 1. 读取 6 个模板文件 const absolute (await readFile(./src/routes/absolute.tsx)).toString() const relative (await readFile(./src/routes/relative.tsx)).toString() const searchRoute (await readFile(./src/routes/search/route.tsx)).toString() const search (await readFile(./src/routes/search/searchPlaceholder.tsx)).toString() const paramsRoute (await readFile(./src/routes/params/route.tsx)).toString() const params (await readFile(./src/routes/params/$paramsPlaceholder.tsx)).toString() // 2. 确保生成目录存在路由目录用 (gen) 分组避免与模板混在一起 if (!existsSync(./src/routes/(gen))) await mkdir(./src/routes/(gen)) if (!existsSync(./src/routes/(gen)/search)) await mkdir(./src/routes/(gen)/search) if (!existsSync(./src/routes/(gen)/params)) await mkdir(./src/routes/(gen)/params) // 3. 写入共享的 route / params 入口 await writeFile(./src/routes/(gen)/search/route.tsx, searchRoute) await writeFile(./src/routes/(gen)/params/route.tsx, paramsRoute) // 4. 循环 100 次每轮生成 4 类路由 for (let y 0; y length; y y 1) { const replacedAbsolute absolute.replaceAll(/absolute, /absolute${y}) const replacedRelative relative.replaceAll(/relative, /relative${y}) const replacedSearch search.replaceAll(searchPlaceholder, search${y}) const replacedParams params.replaceAll(paramsPlaceholder, param${y}) await writeFile(./src/routes/(gen)/absolute${y}.tsx, replacedAbsolute) await writeFile(./src/routes/(gen)/relative${y}.tsx, replacedRelative) await writeFile(./src/routes/(gen)/search/search${y}.tsx, replacedSearch) await writeFile(./src/routes/(gen)/params/$param${y}.tsx, replacedParams) } } main()生成后src/routes目录的实际规模为src/routes/ ├── (gen)/ # 生成路由路由分组语法不影响 URL 层级 │ ├── absolute0..99.tsx # 100 个绝对路径路由 │ ├── relative0..99.tsx # 100 个相对路径路由 │ ├── search/ │ │ ├── route.tsx # /search 布局入口 │ │ └── search0..99.tsx # 100 个带 search 参数的路由 │ └── params/ │ ├── route.tsx # /params 布局入口 │ └── $param0..99.tsx # 100 个带 path 参数的路由 ├── __root.tsx # 根路由含 QueryClient 上下文 ├── absolute.tsx # 模板 ├── index.tsx # 首页 ├── linkProps.tsx ├── params/ ... # 模板 ├── relative.tsx # 模板 └── search/ ... # 模板一次pnpm gen便得到400 条独立路由含(gen)分组、模板与共享路由再配合tanstack/router-plugin在构建期生成包含全部节点的routeTree.gen.tsTypeScript 需要处理的路由字面量类型、Link泛型实例与 search/params 联合类型瞬间被放大两个数量级——这正是本示例想要的压力场景。几个值得注意的工程细节使用(gen)路由分组目录TanStack Router 支持(folder)分组语法括号目录不会进入 URL 路径。这样既可以把生成的路由与手写模板物理隔离又不污染 URL 结构。字符串替换而非 AST 改写replaceAll(/absolute, /absolute${y})这类替换极其轻量100 次循环毫秒级完成因为路由组件内部Link to的值恰好是完整路径字面量直接替换即可保证路径与createFileRoute声明一致。四类路由对应四类类型压力绝对路径to/absolute0、相对路径from{Route.fullPath} to../relative0、search 参数zod schema Link search对象、path 参数to/params/$param0params对象几乎覆盖了 TanStack Router 类型系统的全部重场景。五、模板路由拆解绝对 / 相对 / search / params 四种形态生成的每个路由都源自 6 个手写模板它们共同构成了类型压力测试的原材料。逐一拆解如下。5.1 绝对路径路由最基础的联合类型放大模板 src/routes/absolute.tsximport { Link, createFileRoute } from tanstack/solid-router export const Route createFileRoute(/absolute)({ component: AbsoluteComponent, }) function AbsoluteComponent() { return ( div classp-2 space-y-2 Link to/absolute classblock py-1 text-blue-800 hover:text-blue-600 Absolute /Link /div ) }生成时仅替换to/absolute→to/absolute0…to/absolute99。这 100 个路由的createFileRoute字面量会汇入routeTree.gen.ts的路由联合类型Link to的可选值也随之膨胀为 100 个字符串字面量的联合——这是对 TypeScript 联合类型化简与Link泛型实例化最直接的测试。5.2 相对路径路由from 相对to的推理压力模板 src/routes/relative.tsximport { Link, createFileRoute } from tanstack/solid-router export const Route createFileRoute(/relative)({ component: RelativeComponent, }) function RelativeComponent() { return ( div classp-2 space-y-2 Link from{Route.fullPath} to../relative classblock py-1 text-blue-800 hover:text-blue-600 Relative /Link /div ) }这里to../relative是相对路径其实际指向由from{Route.fullPath}即/relative0…/relative99结合../语义推导。从源码结构看相对导航需要 TypeScript 在当前路由上下文下做更复杂的路径解析与可达性判断相比绝对路径对类型推理的要求更高因此被单独作为一个放大维度。5.3 search 参数路由zod schema query loader 的组合拳模板由两个文件构成。布局入口 src/routes/search/route.tsximport { createFileRoute } from tanstack/solid-router import { z } from zod const search z.object({ rootSearch: z.number(), }) export const Route createFileRoute(/search)({ component: () divHello /search!/div, validateSearch: search, })叶子路由模板 src/routes/search/searchPlaceholder.tsx生成时把searchPlaceholder替换为search0…search99import { Link, createFileRoute } from tanstack/solid-router import { z } from zod import { queryOptions } from tanstack/solid-query const search z.object({ searchPlaceholder: z.literal(searchPlaceholder), page: z.number(), offset: z.number(), search: z.string(), }) const loaderResult z.object({ searchPlaceholder: z.number(), }) const searchQueryOptions queryOptions({ queryKey: [searchPlaceholder], queryFn: () { const result loaderResult.parse({ searchPlaceholder: 0 }) return result }, }) export const Route createFileRoute(/search/searchPlaceholder)({ component: SearchComponent, validateSearch: search, loader: (opts) opts.context.queryClient.ensureQueryData(searchQueryOptions), }) function SearchComponent() { return ( div classp-2 space-y-2 Link to/search/searchPlaceholder classblock py-1 text-blue-800 hover:text-blue-600 search{{ searchPlaceholder: searchPlaceholder, page: 0, offset: 10, search: search, rootSearch: 0, // 父路由 /search 的 rootSearch 也会被继承校验 }} Search /Link /div ) }这一形态集中体现了 TanStack Router 类型安全的重火力validateSearch zodsearch 参数 schema 会转换为精确的 search 类型Link的search属性必须逐字段匹配page、offset、search、字面量searchPlaceholder以及从父路由继承的rootSearch多字段联合校验对类型推理是显著负担loader solid-query路由 loader 通过opts.context.queryClient.ensureQueryData(searchQueryOptions)与全局QueryClient上下文联动上下文类型在__root.tsx中通过createRootRouteWithContextContext()声明见下文这也为类型系统增加了 query 类型层面的实例化压力。5.4 path 参数路由动态段的类型约束布局入口 src/routes/params/route.tsx 较为简单import { createFileRoute } from tanstack/solid-router export const Route createFileRoute(/params)({ component: () divHello /params!/div, })叶子模板 src/routes/params/$paramsPlaceholder.tsx生成时把paramsPlaceholder替换为param0…param99文件名也随之变成$param0.tsx…$param99.tsximport { Link, createFileRoute } from tanstack/solid-router import { z } from zod import { queryOptions } from tanstack/solid-query const params z.object({ oneParamsPlaceholder: z.literal(oneParamsPlaceholder), twoParamsPlaceholder: z.literal(twoParamsPlaceholder), threeParamsPlaceholder: z.literal(threeParamsPlaceholder), }) const loaderResult z.object({ params }) const paramsQueryOptions queryOptions({ queryKey: [paramsPlaceholder], queryFn: () loaderResult.parse({}), }) export const Route createFileRoute(/params/$paramsPlaceholder)({ component: ParamsComponent, loader: (opts) opts.context.queryClient.ensureQueryData(paramsQueryOptions), }) function ParamsComponent() { return ( div classp-2 space-y-2 Link to/params/$paramsPlaceholder params{{ paramsPlaceholder: params }} / /div ) }动态段路由的关键在于$param0.tsx这种文件名即参数名的约定createFileRoute(/params/$param0)声明后Link的params对象必须提供与$param0对应的字段。100 条动态段路由意味着 100 个不同的参数名/参数类型组合同样会显著扩大类型联合与Link泛型参数的类型域。5.5 配套linkProps 与根路由上下文除四类放大路由外示例还包含两个辅助文件src/routes/linkProps.tsx 演示了linkOptions的用法——把Link的 props 抽成可复用配置import { Link, createFileRoute, linkOptions } from tanstack/solid-router export const Route createFileRoute(/linkProps)({ component: LinkPropsPage, }) function LinkPropsPage() { const linkProps linkOptions({ to: /absolute }) return Link {...linkProps} / }src/routes/__root.tsx 是根路由它通过createRootRouteWithContextContext()注入QueryClient并挂载TanStackRouterDevtools便于在浏览器里观察路由匹配情况import { Link, Outlet, createRootRouteWithContext } from tanstack/solid-router import { TanStackRouterDevtools } from tanstack/solid-router-devtools import type { QueryClient } from tanstack/solid-query export interface Context { queryClient: QueryClient } export const Route createRootRouteWithContextContext()({ component: RootComponent, notFoundComponent: () pNot Found (on root route)/p, }) function RootComponent() { return ( div classp-2 flex gap-2 text-lg Link to/ activeProps{{ class: font-bold }} activeOptions{{ exact: true }} Home /Link /div hr / Outlet / TanStackRouterDevtools positionbottom-right / / ) }根路由的Context接口正是 search/params 模板中opts.context.queryClient的类型来源——这一跨文件的类型传播也是整体类型负担的一部分。六、运行时装配main.tsx 与 Vite 插件配置6.1 路由实例的创建与类型注册src/main.tsx 是应用入口负责创建路由实例并注册类型import { render } from solid-js/web import { RouterProvider, createRouter } from tanstack/solid-router import { QueryClient } from tanstack/solid-query import { routeTree } from ./routeTree.gen import ./styles.css export const queryClient new QueryClient() // Set up a Router instance const router createRouter({ routeTree, defaultPreload: intent, context: { queryClient }, scrollRestoration: true, }) // Register things for typesafety declare module tanstack/solid-router { interface Register { router: typeof router } } const rootElement document.getElementById(app)! if (!rootElement.innerHTML) { render(() RouterProvider router{router} /, rootElement) }关键点routeTree来自./routeTree.gen.ts该文件由tanstack/router-plugin在vite build时根据src/routes目录自动生成首次运行pnpm gen后目录膨胀到 400 文件routeTree.gen.ts也会相应变大这是类型压力在运行时的载体。declare moduleRegister接口把router实例类型注册进全局使所有Link、useParams、useSearch等 hook 都能感知到当前路由树——路由树越大这份全局类型就越重这正是本示例要诊断的焦点。defaultPreload: intent与scrollRestoration: true是常规生产配置与性能诊断本身无关仅保证示例在浏览器中可正常演示。6.2 Vite 插件链文件式路由的生成开关vite.config.jsimport { defineConfig } from vite import solid from vite-plugin-solid import { tanstackRouter } from tanstack/router-plugin/vite import tailwindcss from tailwindcss/vite // https://vitejs.dev/config/ export default defineConfig({ plugins: [ tailwindcss(), tanstackRouter({ target: solid, autoCodeSplitting: true }), solid(), ], })tanstackRouter({ target: solid, autoCodeSplitting: true })是文件式路由的开关target: solid指定生成面向 Solid 的代码autoCodeSplitting: true开启路由级自动代码分割。插件会扫描src/routes把全部路由含(gen)分组下的 400 文件编译进routeTree.gen.ts。插件顺序上tanstackRouter放在solid()之前确保路由树生成后再交给 Solid 插件处理 JSX。6.3 tsconfig 配置tsconfig.json 采用 Solid 项目的标准配置{ compilerOptions: { strict: true, esModuleInterop: true, jsx: preserve, jsxImportSource: solid-js, target: ESNext, moduleResolution: Bundler, noEmit: true, skipLibCheck: true, lib: [DOM, DOM.Iterable, ES2022] } }其中jsxImportSource: solid-js是 Solid 生态的必备项skipLibCheck: true用于跳过.d.ts检查避免第三方库类型干扰诊断结果strict: true则确保所有路由类型约束都被完整校验——在pnpm test:types的--extendedDiagnostics输出中这些严格检查的开销都会被如实统计。七、如何阅读诊断输出从tsc --extendedDiagnostics中提取结论pnpm test:types对应tsc --extendedDiagnostics它会在类型检查完成后输出类似下面的统计块数值随路由规模与 TypeScript 版本变化仅示意结构Files: 120 Lines of TypeScript: xxxxx Symbols: xxxxx Types: xxxxx Instantiations: xxxxx Memory used: xxxxxK Assignability cache size: xxxxx Identity cache size: xxxxx Subtype cache size: xxxxx Strict subtype cache size: xxxxx ...解读建议Types与Instantiations是观察路由规模压力的核心指标路由越多createFileRoute字面量与Link泛型实例越多这两项通常接近线性甚至超线性增长。Memory used反映峰值内存占用路由规模爆炸时常伴随明显攀升。各缓存区大小Assignability / Identity / Subtype / Strict subtype暗示类型系统在反复做可赋值性判断——Link to的 100 字面量联合正是这类判断的主要来源。推荐的对比实验方法基线不执行pnpm gen直接pnpm test:types仅模板路由约 10 条记录各项数值与总耗时压力执行pnpm gen后再次pnpm test:types400 路由对比两次输出的差异变量控制还可以修改 createRoutes.mjs 中的const length 100例如改为 50 / 200观察不同规模下的增长曲线从而定位类型性能拐点编译器对比本示例的依赖中 TypeScript 已指向 6/7 预览版见 package.json如需对照可临时将typescript换回稳定版比较--extendedDiagnostics数据评估新编译器对大型路由树的改善程度。注意tsc --extendedDiagnostics的输出是相对且受机器环境影响的跨机器对比意义有限同机同环境下做 A/B 对比才是有效方法。此外pnpm build中已包含一次tsc --noEmit因此完整诊断只需依次执行pnpm gen、pnpm build、pnpm test:types即可。八、诊断之后的优化抓手仓库内可参考的方向本示例的价值在于把问题造出来而问题造出来后如何缓解仓库中其实有对应的成熟方案可作为后续优化实验的落点路由级代码分割示例的 vite.config.js 已开启autoCodeSplitting: true这是控制运行时负担的手段——把 400 路由拆成按需加载的 chunk降低首屏成本。但注意它不直接改善tsc类型检查耗时二者要分开看待。Devtools 观测根路由挂载了 TanStackRouterDevtools浏览器中可直观看到路由匹配、loader 执行情况辅助确认大规模路由树在运行时的实际表现。类型层面的瘦身思路从 router-plugin 与 solid-router 的实现角度出发可以关注routeTree.gen.ts的生成结构、Register全局类型的组织方式以及Link泛型参数的默认值设计——这些都会影响大路由树下的类型开销。具体可结合 router-core 的类型定义进一步分析。九、小结large-file-based示例用最直白的方式回答了 TanStack Router 生态中一个容易被忽略的问题类型安全不是免费的。通过 createRoutes.mjs 的字符串替换批处理一次性把路由规模放大到 400 条覆盖绝对路径、相对路径、search 参数、path 参数四种类型重场景再借助tsc --extendedDiagnostics把类型检查成本量化成Types、Instantiations、Memory used等可对比指标。整个方法论可以概括为四步模板化沉淀 6 个代表路由形态→ 批量化pnpm gen放大规模→ 生成化router-plugin 产出routeTree.gen.ts→ 量化pnpm test:types输出诊断。这套流程不限于本仓库任何使用文件式路由 强类型框架的项目都可以照此搭建自己的路由规模压测台在路由树膨胀失控之前提前摸清类型系统的性能边界。【免费下载链接】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），仅供参考