vite-architecture

@architecture-rules.md @rules/conventions.md @rules/routes.md @rules/services.md @rules/hooks.md @rules/execution-model.md @rules/platform.md @rules/validation.md @references/official/current-docs-2026-06-02.md

Vite + TanStack Router 架构规范执行

<output_language>

默认将所有面向用户的交付物、保存的制品、报告、计划、生成的文档、摘要、交接说明、提交/消息草稿和验证说明设为韩语，即使此规范文件以英语编写。

保留源代码标识符、CLI 命令、文件路径、架构键、JSON/YAML 字段名称、API 名称、包名称、专有名词和引用的源文摘录，并使用其规定的语言或原始语言。

仅当用户明确要求、现有目标制品为保持一致性必须使用其他语言，或机器可读契约要求使用精确的英语令牌时，才使用其他语言。如果存在本地化模板或参考资料（例如 *.ko.md 或 *.ko.json），请优先使用它们来创建面向用户的制品。

</output_language>

• 在执行架构规则前，确认仓库是 Vite + TanStack Router 项目。
• 为客户端可访问的加载器、路由模块、服务层、环境变量用法、生成的路由树和平台设置执行安全边界。
• 应用 Hypercore/仓库本地约定，包括路由文件夹、钩子、服务、命名以及嵌套共享文件夹，例如 src/lib/<domain>/ 和 src/services/<domain-or-provider>/。
• 将最新的 Vite 和 TanStack Router 信息保存在 references/official/ 中，以便在不增加核心规范篇幅的情况下更新快速变化的工具行为。

<routing_rule>

在现有 Vite + TanStack Router 项目中执行架构规范、提供实现指导或进行审查时，使用此规范。这包括路由结构、路由本地文件夹、加载器、validateSearch、服务/查询层、自定义钩子、Vite 插件设置、生成的路由树处理、环境变量/别名安全以及共享嵌套文件夹组织。

如果项目使用 @tanstack/react-start / app.config.ts、项目是未使用 TanStack Router 的通用 Vite 项目，或任务仅涉及文档摘要而不包括项目审计或实现指导，则不要使用此规范。对于 Start 项目，请提供边界说明，指出仅适用于 Start 的接口（createServerFn、useServerFn、Start 中间件 API、app.config.ts），然后停止，不要应用 Vite 路由规则。

当官方 Vite/TanStack Router 指南与 Hypercore 约定不同时，应优先执行官方规则和安全规则，然后仅将 Hypercore 约定应用于涉及的架构部分。

</routing_rule>

<instruction_contract>

字段	约定
意图	确保 Vite + TanStack Router 项目在架构上安全、易于维护，并符合 Vite/Router 官方行为及带标签的 Hypercore 约定。
触发条件	现有 Vite + TanStack Router 项目涉及路由、加载器、搜索参数、服务、钩子、Vite 配置、路由器设置、环境变量/别名边界或共享文件夹布局。
范围	审查并指导涉及的项目架构、主题规则文件、官方参考资料、验证说明，以及小型、可逆的架构修复。
权限	用户/项目指令优先于此技能。对于 API 事实，Vite 和 TanStack Router 官方文档优先于 Hypercore 约定。安全策略会阻止有风险的运行时/环境变量/导入边界变更。
依据	使用项目标识、软件包/配置/路由器本地文件、涉及的源文件路径、主题规则、官方参考资料、软件包检查结果和验证命令输出。
工具	使用本地搜索/读取/编辑/验证命令；API 可能发生变化时查阅最新官方文档；对大范围路由迁移、凭据访问、采用 SSR 和生产环境副作用设置审核关卡。
循环	不进行优化循环。完成架构审查后，最多允许针对 rules/validation.md 中涉及修改范围的检查进行两轮验证与修复；仅当变更仍在涉及范围内且通过这些检查时才保留，并在第 5 步清单通过或报告阻碍因素后停止。
输出	以韩语给出架构决策或审查结果，包括规则分类、变更文件（如有）、验证依据、剩余风险和官方文档歧义说明。
验证	运行 rules/validation.md 中与涉及修改范围相关的检查；若此技能文件夹有变更，则运行 bash scripts/validate-vite-architecture-skill.sh。
停止条件	在确认项目模式、通过适用的安全关卡、应用或明确推迟 Hypercore 约定、记录验证依据，并为尚未解决的 API 变更注明日期和来源后停止。

</instruction_contract>

概述

在编辑代码前，通过严格验证来强制执行 hypercore Vite + TanStack Router 架构规则。

此技能要求严格遵循。必须完全照做，不得例外。

运行模式： 此技能必须保持自包含。仅为应用架构规则，不要依赖外部编排界面。如果仓库本地的持久化循环已经运行，则将这些检查纳入该循环。否则直接使用此技能。

注意： 此技能中的部分规则比 TanStack Router 默认规则更严格。除非用户明确要求遵循 TanStack 官方默认规则，否则请将其视为 hypercore 团队约定。

<activation_examples>

正面示例：

• “在编辑之前，审查这个 Vite + TanStack Router 应用的路由结构、validateSearch 和服务边界。”
• “在 Vite + TanStack Router 应用中添加新的路由文件夹，并确保钩子和服务符合规范。”
• “重构 TanStack Router 页面，让 UI 保留在路由中，并将逻辑移入 -hooks/。”
• “检查 Vite Router 项目中的 tanstackRouter 插件顺序和 routeTree.gen.ts 处理方式。”
• “请像 src/lib/auth/session.ts、src/services/billing/queries.ts 这样使用嵌套文件夹归类，不要放在 src/lib/utils.ts 中。”

负面示例：

• “为浏览器 QA 创建一个新的 Codex 技能。”
• “审查使用 createServerFn 和 @tanstack/react-start 的 TanStack Start 应用。”
• “审查不使用 TanStack Router 的通用 Vite 应用。”

边界示例：

• “在 Vite 路由文件中只做一处微小的文案修改。” 如果修改不涉及架构边界，可以直接编辑；但仍需快速检查被修改的文件是否符合规范。
• “这个仓库实际上使用的是 @tanstack/react-start。” 请返回边界说明，指出应在 Start 项目中处理的 Start 专属部分，而不要将 Vite 规则强加给 Start 项目。

</activation_examples>

<trigger_conditions>

情况	模式
对现有 Vite + TanStack Router 项目的处理涉及路由、加载器、服务、钩子、路由器设置、环境变量、别名或共享文件夹布局	强制执行
存在 @tanstack/react-start 或 app.config.ts	不适用；返回 Start 边界说明
没有 TanStack Router 特征的通用 Vite 项目	不适用
仅在路由文件中修改文案	直接编辑并快速检查规范

</trigger_conditions>

<support_file_read_order>

1. 在修改代码或给出架构问题结论前，先阅读 architecture-rules.md。
2. 阅读与修改范围匹配的主题规则文件：rules/routes.md、rules/services.md、rules/hooks.md、rules/execution-model.md、rules/platform.md、rules/conventions.md 或 rules/validation.md。
3. 仅当 Vite、TanStack Router、插件、环境变量、路由树、搜索参数或加载器行为可能受 API 变更影响时，才阅读直接链接的官方最新文档参考。
4. 编辑此技能文件夹后，运行 bash scripts/validate-vite-architecture-skill.sh。

</support_file_read_order>

第 1 步：项目验证

开始任何工作前，确认这是一个 Vite + TanStack Router 项目：

# Check for Vite + TanStack Router indicators (ANY of these)
grep -r "@tanstack/react-router" package.json 2>/dev/null
grep -r "vite" package.json 2>/dev/null
ls vite.config.ts 2>/dev/null
ls src/routes/__root.tsx 2>/dev/null

如果未找到：停止。此技能不适用。 告知用户，并返回常规实现或审查流程。

如果存在 @tanstack/react-start 或 app.config.ts：停止。 返回 Start 边界说明，指出 Start 专属部分，不要强制应用 Vite 路由规则。

如果仓库符合 Vite + TanStack Router 条件：继续执行架构规范。

## 步骤 2：阅读架构规则

加载详细的规则参考：

必需： 编写任何代码之前，先阅读此技能目录中的 architecture-rules.md。如果 Vite 配置、环境变量处理、TanStack Router 插件设置、routeTree 生成或搜索／加载行为可能受 API 漂移影响，请阅读 references/official/current-docs-2026-06-02.md。

如需查看详细模式和示例，也请阅读相关规则文件：

• rules/conventions.md - 命名、TypeScript、导入、注释
• rules/routes.md - 路由文件夹结构、route.tsx、加载器、搜索参数
• rules/services.md - 公共 API 服务、查询选项、变更、客户端边界
• rules/hooks.md - 自定义 Hook 的拆分和内部顺序
• rules/execution-model.md - 加载器／运行时边界、SSR 注意事项、环境变量安全
• rules/platform.md - vite.config.ts、路由器设置、生成文件、环境变量和别名规则
• rules/validation.md - 项目／技能验证和回读检查

步骤 3：变更前验证清单

编写任何代码之前，先根据以下关卡验证计划中的变更：

棕地采用规则

• 不要把所有未触及的遗留偏差都视为需要立即在整个项目中解决的问题。
• 安全或边界问题仍须立即阻止，尤其是在已修改的文件中。
• 未触及的遗留代码中偏离 Hypercore 特定风格或结构的问题，可以记录为迁移待办事项。
• 任何已修改的文件都应符合规范，除非这样做会导致实质性风险迁移。

关卡 1：分层违规

Routes -> Services -> External API

检查项	规则
路由是否直接调用 fetch/axios？	禁止。必须通过服务调用
Hook 是否直接调用 fetch/axios？	禁止。必须通过服务调用
服务是否向路由／Hook 返回原始 Response？	禁止。应返回类型化数据
在 Vite 应用中使用 createServerFn、useServerFn 或仅适用于 Start 的中间件 API？	禁止

关卡 2：路由结构

检查项	规则
承载 UI／逻辑的页面是否使用了扁平文件路由？（routes/users.tsx）	禁止。使用文件夹路由（routes/users/index.tsx）
是否缺少 -components/ 文件夹？	禁止。每个页面都必须有该文件夹
是否缺少 -hooks/ 文件夹？	禁止。每个页面都必须有该文件夹
是否存在 -functions/ 文件夹？	禁止。Vite 技能不允许使用服务端函数
const Route 是否未导出？	禁止。必须使用 export const Route
页面组件中是否包含逻辑？	禁止。应提取到 -hooks/
布局路由是否在负责共享加载器／beforeLoad／布局逻辑时缺少 route.tsx？	禁止
路由是否带有搜索参数却没有 validateSearch？	禁止。使用 zodValidator
路由是否有加载器却没有 pendingComponent？	警告。建议添加

关卡 3：服务

检查项	规则
POST/PUT/PATCH 是否未进行模式验证？	禁止。调用前使用 Zod 验证
路由或 Hook 中是否直接使用 fetch/axios？	禁止。使用服务函数
是否存在 services/index.ts 桶形导出文件？	禁止。直接从具体文件导入
服务函数是否缺少显式返回类型？	禁止

关卡 4：Hook

检查项	规则
Hook 逻辑是否仍留在页面组件中？	禁止。移至 -hooks/
Hook 顺序是否错误？	禁止。State -> Global -> Query -> Handlers -> Memo -> Effect
是否缺少已导出的返回类型接口？	禁止
Hook 文件名是否使用 camelCase？	禁止。使用 use-kebab-case.ts
Vite Hook 中是否使用 useServerFn？	禁止

关卡 5：规范

检查项	规则
文件名是否使用 camelCase？	禁止。使用 kebab-case
是否使用 function 关键字？	禁止。使用 const 箭头函数
是否使用 any 类型？	禁止。使用 unknown
是否缺少显式返回类型？	禁止
导入顺序是否错误？	禁止。External -> @/ -> Relative -> Type
分组逻辑是否缺少韩语块注释？	禁止
是否使用 z.string().email()？	禁止。在 Zod 4 中使用 z.email()

Gate 6：执行模型

检查项	规则
将路由 loader 视为仅限服务端的私有边界？	已阻止。Loader 可由客户端访问，也可能参与 SSR／手动渲染
在路由模块或 loader 中访问密钥、数据库、文件系统或特权 SDK？	已阻止。请将其置于实际的后端／API 边界之后
在模块作用域或共享路由辅助函数中使用仅限浏览器的 API，且没有客户端边界？	已阻止
在客户端可访问的代码中访问非 VITE_ 环境变量？	已阻止

Gate 7：平台设置

检查项	规则
vite.config.ts 缺少 tanstackRouter()，或插件顺序错误？	已阻止。路由器插件必须显式配置，并置于 react() 之前
手动编辑 routeTree.gen.ts？	已阻止。请将其视为生成的输出
路由器设置隐藏不明，或与 SSR／手动渲染需求不一致？	警告。请明确配置 src/router.tsx；存在 SSR／手动渲染时，请使用全新的路由器工厂
路径别名或环境变量设置仅依赖隐式行为？	警告。请明确配置 tsconfig／Vite 配置和运行时验证

步骤 3.5：自动修复策略

当问题局部、可逆且风险较低时，直接自动修复。

• 添加缺失的 validateSearch
• 将路由／钩子中直接发起的网络请求移至 services/
• 添加缺失的 pendingComponent 或 errorComponent
• 为已修改的页面创建缺失的 -components/ 或 -hooks/ 文件夹
• 添加或更正 tanstackRouter() 插件设置、路由器脚手架，或显式的环境变量／别名配置

未经明确说明理由，不要自动应用范围广或可能造成破坏的迁移。

• 批量重命名路由／文件
• 跨多个页面大规模重构路由树
• 在仅使用 SPA 的代码库中引入 SSR／手动服务端渲染
• 大规模重写身份验证或 API 客户端

步骤 4：实现

将以下验收标准纳入当前任务：

- [ ] Layer architecture respected (Routes -> Services -> External API)
- [ ] Route uses folder structure with -components/ and -hooks/
- [ ] export const Route = createFileRoute(...) used
- [ ] No Start-only server-function APIs in this Vite project
- [ ] Search params use zodValidator from @tanstack/zod-adapter
- [ ] Custom Hooks live in -hooks/ with correct internal order
- [ ] Loaders stay public-safe and SSR-safe
- [ ] Vite/router platform setup stays explicit (router plugin, router file, generated files)
- [ ] All filenames kebab-case
- [ ] Korean block comments present
- [ ] const arrow functions with explicit return types

<validation_checklist>

步骤 5：变更后验证

编写代码后，验证以下内容：

1. 结构检查：确认每个已修改的页面仍有 -components/ 和 -hooks/，且没有 -functions/
2. 导出检查：搜索 export const Route
3. 分层检查：已修改的路由或钩子文件中没有直接使用 fetch／axios
4. 约定检查：没有 camelCase 文件名，也没有 function 关键字声明
5. 钩子顺序检查：阅读已修改的钩子，并验证顺序为 State -> Global -> Query -> Handlers -> Memo -> Effect
6. 执行检查：loader 和路由模块不会直接访问密钥、数据库客户端或私有环境变量
7. 平台检查：vite.config.ts、src/router.tsx、环境变量配置和生成的路由器文件保持一致

</validation_checklist>