TanStack Start 的 no-async-client-component 规则：基于渲染图的异步组件客户端上下文静态检测

TanStack Start 的 no-async-client-component 规则基于渲染图的异步组件客户端上下文静态检测【免费下载链接】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在 React Server ComponentsRSC架构下async组件只能在服务端被await而客户端组件一旦声明为asyncReact 会在运行时直接抛出异常。TanStack Start 的 ESLint 插件tanstack/eslint-plugin-start提供了no-async-client-component规则利用 TypeScript 类型系统在编译期构建全程序的组件渲染图render graph通过传播 server/client 上下文来静态判定每个组件最终落在哪一侧从而在async组件真正进入客户端上下文之前就将其拦截。本文将基于该规则的设计文档 no-async-client-component.md 与其完整源码实现深入讲解它的检测算法、关键数据结构、边界情况与性能设计帮助你理解并正确使用这条规则。规则要解决的问题在 RSC 模型中组件分为服务端组件与客户端组件两大类二者对async的支持完全不同服务端组件async组件是合法的组件函数体内可以await数据请求渲染逻辑在服务端执行客户端组件不能是async函数React 会在运行时直接抛出错误。客户端组件的渲染结果需要被序列化并水合hydrate异步函数体无法完成这一过程。因此组件是否会进入客户端上下文是判断async是否合法的唯一标准。设计文档明确了组件成为客户端组件的三条途径被createFileRoute()或createRootRoute()的路由选项引用component、pendingComponent、errorComponent、notFoundComponent等位于带use client指令的文件中被另一个客户端组件渲染传递性地成为客户端组件。no-async-client-component规则的价值就在于静态地、跨文件地把这三条途径全部建模出来任何一个async组件只要落入客户端上下文就会同时在定义处和JSX 使用处被报告。规则定位与启用方式该规则属于tanstack/eslint-plugin-start插件定义见 index.ts类型为problem在插件内置的recommended与flat/recommended配置中默认以error级别开启// flat/recommended { plugins: { tanstack/start: plugin }, rules: { tanstack/start/no-client-code-in-server-component: error, tanstack/start/no-async-client-component: error, }, }也可以在任何 ESLint 配置中单独启用并覆盖默认选项// eslint.config.js import eslintPluginStart from tanstack/eslint-plugin-start export default [ eslintPluginStart.configs[flat/recommended], { rules: { tanstack/start/no-async-client-component: [ error, { ignorePatterns: [src/legacy/**] }, ], }, }, ]插件要求 peer 依赖eslint ^8.57.0 || ^9.0.0 || ^10.0.0与typescript 4.7.0见 package.json因为规则需要从 ESLint parser services 中获取 TypeScript program 进行符号解析。核心检测算法三个阶段规则的核心是设计文档中描述的三阶段算法源码实现render-graph-builder.ts 与 context-analyzer.ts与文档严格对应。Phase 1构建全程序渲染图render graph利用 ESLint parser services 提供的 TypeScript program对程序内每个文件索引组件定义收集 PascalCase 命名的导出函数或赋值给箭头函数/普通函数的 const 变量async属性通过 TS 节点的AsyncKeywordmodifier 判断对应hasAsyncModifier寻找 JSX 使用点扫描Component /形式的 JSX 元素通过checker.getSymbolAtLocation(tagName)解析符号构建callerComponent - calleeComponent的渲染边标记服务端根server rootscreateServerComponent()回调本身以及该回调 JSX 树内引用的组件标记客户端根client rootscreateFileRoute()/createRootRoute()各组件选项引用的组件以及带use client指令的文件内的组件。需要特别说明的是文档以createServerComponent()作为服务端根的概念化表述而当前实现constants.ts实际识别的是tanstack/react-start/rsc中真实存在的两个服务端渲染 API ——renderServerComponent与createCompositeComponent它们也是仓库中 RSC 服务端组件的实际入口参见 server-components/SKILL.md。同时文档明确了两点范围约定createRootRoute/createFileRoute指tanstack/react-router的 APIcreateLazyFileRoute故意不在检测范围内惰性路由不做静态分析。Phase 2传播上下文在渲染图上进行两次传播1. 将全部服务端根标记为 server context 2. 从服务端根出发遍历渲染图将后代标记为 server context - 遇到 use client 边界立即停止边界之后的组件进入客户端 3. 将全部客户端根标记为 client context 4. 从客户端根出发遍历渲染图将后代标记为 client context 5. 同时被两种上下文可达的组件视为 tainted客户端获胜 6. 无法被服务端上下文到达的组件一律视为 client context注意文档给出的关键推论如果程序中没有服务端根没有任何createServerComponent使用那么所有组件都会落入客户端上下文此时任何async组件都是非法的。源码实现中propagateServerContext在遇到use client文件时会把该组件直接标记为客户端上下文并停止向下传播propagateClientContext则从客户端根出发把沿途后代标记为客户端上下文并记录被哪个父组件渲染rendered-by-client作为违规原因。Phase 3报告违规对每个async组件若组件处于客户端上下文在组件定义处报告主报告点在每个调用方组件处于客户端上下文的 JSX 使用点报告次级报告点。关键数据结构文档中定义的核心类型在 render-graph-builder.ts 与 context-analyzer.ts 中原样落地interface ComponentInfo { name: string fileName: string node: ts.Node isAsync: boolean line: number } interface RenderEdge { fromFile: string fromComponent: string toFile: string toComponent: string jsxNode: ts.Node // 用于在使用点报告 } interface ComponentContext { component: ComponentInfo isServerContext: boolean isClientContext: boolean // 如果是客户端上下文原因是什么 clientReason?: | { type: use-client } | { type: route-option; routeFile: string; option: string } | { type: rendered-by-client; parentComponent: string } } type RenderGraph { components: Mapstring, ComponentInfo // key: file:ComponentName edges: ArrayRenderEdge serverRoots: Setstring // createServerComponent 内的组件 clientRoots: Setstring // 路由选项或 use client 文件中的组件 }实现版RenderGraph还额外携带了useClientFiles、routeOptionUsages路由选项使用信息用于更精确的错误定位以及按文件索引的routeOptionRootsByFile帮助在按需子图分析时快速定位当前文件的入口根。组件以fileName:ComponentName作为全局唯一 key跨文件重名组件因此不会互相污染。追踪的路由选项与服务端根constants.ts 集中定义了规则追踪的全部名称常量// 接受组件引用的路由选项这些选项使被引用组件成为 client root export const ROUTE_COMPONENT_OPTION_NAMES [ component, pendingComponent, errorComponent, notFoundComponent, ] as const // 创建路由客户端入口的函数名 export const ROUTE_CREATOR_NAMES [ createFileRoute, createRootRoute, createRootRouteWithContext, ] as const // 创建服务端组件根的函数名 export const SERVER_COMPONENT_ROOTS [ renderServerComponent, createCompositeComponent, ] as const在render-graph-builder.ts中getRouteOptionsObject会从调用表达式的 callee 一路回溯支持createFileRoute(/x)({ ... })、createRootRoute()({ ... })、createRootRouteWithContextT()({ ... })以及括号包裹、链式调用等形态确认其来源属于ROUTE_CREATOR_NAMES后才把选项对象纳入分析随后只对ROUTE_COMPONENT_OPTION_NAMES中的键做处理且仅当值解析为函数/组件引用标识符、内联函数等时才标记为客户端根。源码实现细节按需分析与缓存规则主文件 no-async-client-component.rule.ts 在文档算法基础上做了重要的工程化处理核心是避免对全程序做无谓的完整图构建快速门控gating在Program访问器内先用字符串快速检查当前文件是否包含路由选项关键字createFileRoute/createRootRoute/createRootRouteWithContext且含组件选项名、服务端组件根renderServerComponent/createCompositeComponent或use client指令三者皆无的文件直接跳过几乎零成本按需子图on-demand slicing只对当前入口文件可达的组件做子图切片再在该子图上做上下文分析。若文件含路由选项但切片结果没有任何根例如符号解析失败则回退到完整图分析保证不误报漏报三级缓存用WeakMapts.Program, ...缓存每个 program 的图构建器与是否已构建标记用另一个WeakMap缓存每个入口文件的子图与分析结果再用adjacencyCache缓存邻接表避免反复扫描全部边去重报告通过reportedSet 按def:key与usage:file:line:component两种 key 去重防止同一违规被重复上报。sliceGraphForEntryFile的实现细节值得留意它利用routeOptionRootsByFile索引做到 O(该文件根数) 的快速定位同时把use client文件内的所有本地组件视为客户端根。这一整套惰性入口分析方案的动机与效果记录在 lint-improvements.md 中对于5000 个文件、10 个路由、每条路由 50 个组件的典型场景文件访问量从约 5000 降到约 500约 10x组件索引量从约 2000 降到约 500约 4x内存占用从全图驻留降为仅活动路径约为 10x 的改善。边界情况文档列举了五种典型边界情况规则均给出了明确行为1. 组件同时被服务端与客户端使用tainted// ServerPage.tsx createServerComponent(() SharedComponent /) // 服务端使用 // ClientPage.tsx createFileRoute(/)({ component: () SharedComponent / }) // 客户端使用结果报错 ——SharedComponent被客户端上下文污染客户端获胜。2. 条件渲染createServerComponent(() { if (condition) return AsyncComponent / // 合法 return SyncComponent / })结果AsyncComponent处于服务端上下文合法不报告。3. 动态导入const LazyComponent lazy(() import(./AsyncComponent))结果最初阶段不在检测范围内静态解析成本过高、不具确定性。4. 组件作为 prop 传入slotcreateServerComponent(({ ActionButton }) { return ( div ActionButton / /div ) // ActionButton 来自客户端 })结果ActionButton是来自客户端的插槽slot单独追踪不判定为服务端组件。5. 再导出re-exports// components/index.ts export { MyComponent } from ./MyComponent结果通过 TS 符号解析alias symbol跟随再导出链最终定位到真实定义文件。源码中符号解析通过resolveSymbol实现当符号带有SymbolFlags.Alias时调用checker.getAliasedSymbol(symbol)解引用见render-graph-builder.ts。错误消息规则在定义处与使用处分别给出两条消息与 no-async-client-component.rule.ts 的messages定义一致其中定义处消息会附带{{reason}}说明违规原因定义处Async component MyComponent cannot be used in client context. Async components are only valid inside server components. Either remove async or ensure this component is only rendered within server components.使用处Async component MyComponent is rendered in client context here. Async components are only valid inside server components. Move this to a server component or use a non-async version.formatReason会根据ClientReason的三种类型输出原因File has use client directive.Component is referenced by a route option (createFileRoute/createRootRoute).Rendered by client component Xxx in 相对路径.还有一个值得一提的细节当违规原因是route-option时规则只在路由文件的使用点上报避免在远方的定义文件里报一个难以定位的错误而use-client与rendered-by-client场景则在定义处上报。规则选项文档定义的RuleOptions如下interface RuleOptions { /** * 额外视为客户端入口的文件模式 * default [] */ additionalClientPatterns?: string[] /** * 需要忽略的文件模式 * default [] */ ignorePatterns?: string[] }需要说明的是当前源码实现schema 定义见no-async-client-component.rule.ts的meta.schema实际暴露的选项为ignorePatterns字符串数组additionalProperties: falseshouldIgnore通过filePath.includes(pattern)做子串匹配来决定跳过哪些文件additionalClientPatterns属于文档中的规划项尚未在实现中落地。使用时以当前版本实际支持的ignorePatterns为准。测试用例仓库在 no-async-client-component.rule.test.ts 中通过RuleTester基于typescript-eslint/rule-tester开启 JSX 与 TypeScript project service完整验证了文档中的用例。合法用例不应报告// Async 出现在 createCompositeComponent 内服务端根 import { createCompositeComponent } from tanstack/react-start/rsc createCompositeComponent(async () { const data await fetch(/api) return div{data}/div }) // async 组件被服务端组件渲染 // AsyncData.tsx export async function AsyncData() { return div{await getData()}/div } // ServerPage.tsx createServerComponent(() AsyncData /) // 同步组件在客户端上下文合法 createFileRoute(/)({ component: SyncComponent })非法用例应报告// async 组件直接作为路由组件 export async function Page() { return div / } createFileRoute(/)({ component: Page }) // 两处都报错 // async 组件被客户端组件渲染 // AsyncWidget.tsx export async function AsyncWidget() { return div / } // ClientPage.tsx createFileRoute(/)({ component: () AsyncWidget /, // 报错AsyncWidget 是 async }) // use client 文件中的 async 组件 (use client) export async function ClientComponent() { return div / } // 报错 // async 组件被 use client 文件渲染 // Widget.tsx export async function Widget() { return div / } // ClientWrapper.tsx (use client) import { Widget } from ./Widget export function Wrapper() { return Widget / } // 使用处报错Widget.tsx 定义处也报错 // 传递性的客户端上下文 // AsyncDeep.tsx export async function AsyncDeep() { return div / } // Middle.tsx export function Middle() { return AsyncDeep / } // ClientPage.tsx createFileRoute(/)({ component: () Middle / }) // 报错AsyncDeep 被传递性地渲染在客户端上下文测试还覆盖了更多形态createRootRoute与createRootRouteWithContextMyRouterContext()()中的 async 组件、async 箭头函数组件const AsyncPage async () ...、asyncpendingComponent/errorComponent、以及同一文件内多个 async 组件同时违规的情况。与其他规则的关系tanstack/eslint-plugin-start目前包含两条规则注册见 rules.tsno-async-client-component本文主题负责 async 组件no-client-code-in-server-component负责客户端专属代码hooks、onClick等混入服务端组件。两者共享同一套use client判定基础设施 —— use-client-resolver.ts从no-client-code-in-server-component提取到共享目录。lint-improvements.md规划了把两条规则的传递分析统一收敛到共享的transitive-walker使规则在保持相同报错行为的同时进一步提升性能。理解这两条规则的配合可以在 RSC 项目中同时守住服务端组件不能引用客户端代码与客户端组件不能是 async两条边界。实现步骤与依赖文档给出了规则的完整落地路径与仓库现状一一对应创建async-component-detector.ts查找文件中的 async 函数组件export async function Foo()、export const Foo async () {}组件启发式为 PascalCase 命名创建render-graph-builder.ts遍历 TS program 全部文件构建 JSX 渲染边识别服务端根与客户端根创建context-analyzer.ts从两侧根出发传播上下文处理use client边界得出每个组件的最终上下文创建no-async-client-component.rule.ts在Program节点上构建/缓存渲染图检查 async 组件上下文并报告定义处与使用处双报告点添加测试合法/非法/边界混合、传递、再导出三类用例更新插件导出注册到rules.ts与index.ts。依赖方面规则复用现有use-client-resolver.ts通过 ESLint parser services 获取 TypeScript program不引入任何新的外部依赖——这是它能够跨文件静态分析却保持轻量的原因。结语no-async-client-component是 RSC 项目中一道关键的编译期防线。它把组件最终渲染在哪一侧这个运行时问题转化为渲染图上的上下文传播问题用 TypeScript 符号系统实现了跨文件、可传递、可解释的静态判定并在实现层面通过门控、按需切片与三级缓存做到了大规模项目可用。对于正在使用 TanStack Start 的 RSC 能力renderServerComponent/createCompositeComponent并配合文件路由createFileRoute/createRootRoute的团队在flat/recommended配置中默认开启的这条规则可以让async 组件误入客户端上下文这类运行时崩溃在 CI 阶段就被提前消灭。【免费下载链接】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），仅供参考