vite-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vite + TanStack Router Architecture Enforcement

Vite + TanStack Router 架构强制执行

Overview

概述

Enforces hypercore Vite + TanStack Router architecture rules with strict validation before editing code.

This skill is RIGID. Follow exactly. No exceptions.

OPERATING MODE: This skill must stay self-contained. Do not block on external orchestration surfaces just to apply architecture rules. If a repo-local persistence loop is already active, carry these gates into that loop. Otherwise proceed directly with this skill.

NOTE: Some rules in this skill are stricter than TanStack Router defaults. Treat them as hypercore team conventions unless the user explicitly asks to follow official TanStack defaults instead.

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

本规则严格执行，必须完全遵循，无例外。

运行模式： 本规则必须独立执行。不得为了应用架构规则而依赖外部编排流程。如果仓库本地已有持久化循环机制，需将这些校验规则融入该循环；否则直接执行本规则。

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

Trigger Examples

触发示例

Positive

适用场景

Audit this Vite + TanStack Router app for route structure, validateSearch, and service boundaries before editing.

Add a new route folder in a Vite + TanStack Router app and keep hooks/services compliant.

Refactor a TanStack Router page so the UI stays in the route and logic moves into -hooks/.

在编辑前审核这个Vite + TanStack Router应用的路由结构、validateSearch和服务边界。

在Vite + TanStack Router应用中添加新路由文件夹，并确保钩子/服务符合规范。

重构TanStack Router页面，使UI保留在路由中，逻辑迁移至-hooks/目录。

Negative

不适用场景

Create a new Codex skill for browser QA.

Review a TanStack Start app that uses createServerFn and @tanstack/react-start.

为浏览器QA创建新的Codex技能。

审查使用createServerFn和@tanstack/react-start的TanStack Start应用。

Boundary

边界场景

```
Make a tiny copy-only text change in a Vite route file.
```
Direct editing can be enough if the change does not cross an architecture boundary, but touched files still need a quick compliance check.

The repo actually uses @tanstack/react-start.

Route away to

tanstack-start-architecture

instead of forcing Vite rules onto a Start project.

```
在Vite路由文件中进行微小的纯文本复制修改。
```
如果变更未跨越架构边界，可直接编辑，但仍需对涉及文件进行快速合规性检查。

仓库实际使用@tanstack/react-start。

应切换至

tanstack-start-architecture

规则，而非将Vite规则强制应用于Start项目。

Step 1: Project Validation

步骤1：项目验证

Before any work, confirm a Vite + TanStack Router project:

bash

undefined

在开展任何工作前，确认项目为Vite + TanStack Router项目：

bash

undefined

Check for Vite + TanStack Router indicators (ANY of these)

检查Vite + TanStack Router标识（满足任意一项即可）

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


If NONE found: **STOP. This skill does not apply.** Inform the user and return to the normal implementation or review path.

If `@tanstack/react-start` or `app.config.ts` is present: **STOP.** Route to `tanstack-start-architecture`.

If the repo matches Vite + TanStack Router: proceed with architecture enforcement.

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`：**停止执行。** 切换至`tanstack-start-architecture`规则。

如果仓库符合Vite + TanStack Router项目特征：继续执行架构强制规则。

Step 2: Read Architecture Rules

步骤2：阅读架构规则

Load the detailed rules reference:

REQUIRED: Read

architecture-rules.md

in this skill directory before writing any code.

For detailed patterns and examples, also read the relevant rule files:

```
rules/conventions.md
```
- naming, TypeScript, imports, comments
```
rules/routes.md
```
- route folder structure,
```
route.tsx
```
, loaders, search params
```
rules/services.md
```
- public API services, query options, mutations, client boundaries
```
rules/hooks.md
```
- custom hook separation and internal order
```
rules/execution-model.md
```
- loader/runtime boundaries, SSR-aware caveats, env safety
```
rules/platform.md
```
-
```
vite.config.ts
```
, router setup, generated files, env and alias rules

加载详细规则参考：

必须执行： 在编写任何代码前，阅读本规则目录下的

architecture-rules.md

文件。

如需详细模式和示例，还需阅读相关规则文件：

```
rules/conventions.md
```
- 命名规范、TypeScript、导入规则、注释要求
```
rules/routes.md
```
- 路由文件夹结构、
```
route.tsx
```
、加载器、搜索参数
```
rules/services.md
```
- 公共API服务、查询选项、变更操作、客户端边界
```
rules/hooks.md
```
- 自定义钩子分离规则及内部顺序
```
rules/execution-model.md
```
- 加载器/运行时边界、SSR注意事项、环境变量安全
```
rules/platform.md
```
-
```
vite.config.ts
```
、路由配置、生成文件、环境变量及别名规则

Step 3: Pre-Change Validation Checklist

步骤3：变更前校验清单

Before writing ANY code, verify the planned change against these gates:

在编写任何代码前，验证计划变更是否符合以下校验项：

Brownfield Adoption Rule

遗留项目适配规则

Do not treat every untouched legacy deviation as an immediate project-wide failure.
Safety or boundary issues still block immediately, especially in touched files.
Hypercore-specific style or structure drift in untouched legacy code can be recorded as migration backlog.
Any file you touch should be brought into compliance unless that would require a materially risky migration.

不要将所有未修改的遗留代码偏差视为立即需要修复的项目级问题。
安全或边界问题仍需立即阻止，尤其是在涉及修改的文件中。
未修改的遗留代码中不符合hypercore风格或结构的部分可记录为迁移待办项。
除非存在重大迁移风险，否则所有你修改的文件都必须符合规范。

Gate 1: Layer Violations

校验项1：分层违规

Routes -> Services -> External API

Check	Rule
Route calling `fetch` / `axios` directly?	BLOCKED. Must go through services
Hook calling `fetch` / `axios` directly?	BLOCKED. Must go through services
Service returning raw `Response` to routes/hooks?	BLOCKED. Return typed data
`createServerFn` , `useServerFn` , or Start-only middleware APIs in a Vite app?	BLOCKED

路由层 -> 服务层 -> 外部API

检查内容	规则
路由直接调用 `fetch` / `axios` ？	禁止。必须通过服务层调用
钩子直接调用 `fetch` / `axios` ？	禁止。必须通过服务层调用
服务层向路由/钩子返回原始 `Response` ？	禁止。需返回类型化数据
Vite应用中使用 `createServerFn` 、 `useServerFn` 或Start专属中间件API？	禁止

Gate 2: Route Structure

校验项2：路由结构

Check	Rule
Flat file route for a page that owns UI/logic? ( `routes/users.tsx` )	BLOCKED. Use a folder route ( `routes/users/index.tsx` )
Missing `-components/` folder?	BLOCKED. Every page needs it
Missing `-hooks/` folder?	BLOCKED. Every page needs it
`-functions/` folder present?	BLOCKED. Vite skill does not allow server functions
`const Route` without `export` ?	BLOCKED. Must be `export const Route`
Logic in page component?	BLOCKED. Extract to `-hooks/`
Layout route missing `route.tsx` while it owns shared loader/beforeLoad/layout work?	BLOCKED
Route with search params but no `validateSearch` ?	BLOCKED. Use `zodValidator`
Route with loader but no `pendingComponent` ?	WARNING. Recommended

检查内容	规则
拥有UI/逻辑的页面使用扁平文件路由（ `routes/users.tsx` ）？	禁止。需使用文件夹路由（ `routes/users/index.tsx` ）
缺少 `-components/` 文件夹？	禁止。每个页面都必须包含该文件夹
缺少 `-hooks/` 文件夹？	禁止。每个页面都必须包含该文件夹
存在 `-functions/` 文件夹？	禁止。Vite规则不允许使用服务端函数
`const Route` 未添加 `export` ？	禁止。必须写为 `export const Route`
页面组件中包含逻辑代码？	禁止。需提取至 `-hooks/` 目录
布局路由拥有共享加载器/beforeLoad/布局逻辑但缺少 `route.tsx` ？	禁止
使用搜索参数但未配置 `validateSearch` ？	禁止。需使用 `zodValidator`
路由配置了加载器但未设置 `pendingComponent` ？	警告。建议配置

Gate 3: Services

校验项3：服务层

Check	Rule
POST/PUT/PATCH without schema validation?	BLOCKED. Validate with Zod before calling
Direct `fetch` / `axios` in route or hook?	BLOCKED. Use service functions
`services/index.ts` barrel export?	BLOCKED. Import directly from concrete files
Missing explicit return type on service function?	BLOCKED

检查内容	规则
POST/PUT/PATCH请求未进行Schema校验？	禁止。调用前需使用Zod进行校验
路由或钩子中直接使用 `fetch` / `axios` ？	禁止。需使用服务层函数
使用 `services/index.ts` 桶式导出？	禁止。需直接从具体文件导入
服务层函数缺少显式返回类型？	禁止

Gate 4: Hooks

校验项4：钩子

Check	Rule
Hook logic left inside page component?	BLOCKED. Move to `-hooks/`
Wrong hook order?	BLOCKED. State -> Global -> Query -> Handlers -> Memo -> Effect
Missing exported return type interface?	BLOCKED
camelCase hook filename?	BLOCKED. Use `use-kebab-case.ts`
`useServerFn` in a Vite hook?	BLOCKED

检查内容	规则
钩子逻辑留在页面组件中？	禁止。需迁移至 `-hooks/` 目录
钩子内部顺序错误？	禁止。正确顺序：状态 -> 全局 -> 查询 -> 处理器 -> 计算属性 -> 副作用
缺少导出的返回类型接口？	禁止
钩子文件名使用小驼峰命名？	禁止。需使用 `use-kebab-case.ts` 格式
Vite钩子中使用 `useServerFn` ？	禁止

Gate 5: Conventions

校验项5：编码约定

Check	Rule
camelCase filename?	BLOCKED. Use kebab-case
`function` keyword?	BLOCKED. Use const arrow functions
`any` type?	BLOCKED. Use `unknown`
Missing explicit return type?	BLOCKED
Wrong import order?	BLOCKED. External -> @/ -> Relative -> Type
Missing Korean block comments for grouped logic?	BLOCKED
Using `z.string().email()` ?	BLOCKED. Use `z.email()` in Zod 4

检查内容	规则
文件名使用小驼峰命名？	禁止。需使用短横线分隔命名
使用 `function` 关键字声明函数？	禁止。需使用箭头函数表达式
使用 `any` 类型？	禁止。需使用 `unknown`
缺少显式返回类型？	禁止
导入顺序错误？	禁止。正确顺序：外部依赖 -> @/别名 -> 相对路径 -> 类型导入
分组逻辑缺少韩文块注释？	禁止
使用 `z.string().email()` ？	禁止。Zod 4中需使用 `z.email()`

Gate 6: Execution Model

校验项6：执行模型

Check	Rule
Treating a route `loader` as a private server-only boundary?	BLOCKED. Loaders are client-reachable and may also participate in SSR/manual rendering
Secret, DB, filesystem, or privileged SDK access inside a route module or loader?	BLOCKED. Keep it behind an actual backend/API boundary
Browser-only APIs used at module scope or in shared route helpers without a client boundary?	BLOCKED
Non- `VITE_` env access in client-reachable code?	BLOCKED

检查内容	规则
将路由 `loader` 视为私有服务端专属边界？	禁止。加载器可被客户端访问，也可能参与SSR/手动渲染
路由模块或加载器中访问密钥、数据库、文件系统或特权SDK？	禁止。需将这些逻辑放在真实后端/API边界之后
在模块作用域或共享路由工具中使用浏览器专属API但未设置客户端边界？	禁止
在客户端可访问代码中使用非 `VITE_` 前缀的环境变量？	禁止

Gate 7: Platform Setup

校验项7：平台配置

Check	Rule
`vite.config.ts` missing `tanstackRouter()` or plugin order is wrong?	BLOCKED. Router plugin must stay explicit and precede `react()`
`routeTree.gen.ts` hand-edited?	BLOCKED. Treat as generated output
Router setup hidden or inconsistent with SSR/manual rendering needs?	WARNING. Keep `src/router.tsx` explicit; use a fresh router factory when SSR/manual rendering exists
Path alias or env setup relies on implicit behavior only?	WARNING. Keep `tsconfig` /Vite config and runtime validation explicit

检查内容	规则
`vite.config.ts` 中缺少 `tanstackRouter()` 或插件顺序错误？	禁止。路由插件必须显式配置且位于 `react()` 插件之前
手动编辑 `routeTree.gen.ts` ？	禁止。该文件为自动生成文件
路由配置隐藏或与SSR/手动渲染需求不一致？	警告。需保持 `src/router.tsx` 显式配置；当存在SSR/手动渲染时，使用全新的路由工厂
路径别名或环境变量配置仅依赖隐式行为？	警告。需保持 `tsconfig` /Vite配置及运行时校验的显式性

Step 3.5: Auto-Remediation Policy

步骤3.5：自动修复策略

Auto-fix directly when the issue is local, reversible, and low-risk.

add missing
```
validateSearch
```
move direct route/hook network access into
```
services/
```
add missing
```
pendingComponent
```
or
```
errorComponent
```
create missing
```
-components/
```
or
```
-hooks/
```
folders for touched pages
add or correct
```
tanstackRouter()
```
plugin setup, router scaffolding, or explicit env/alias wiring

Do not auto-apply broad or potentially breaking migrations without explicit justification.

mass route/file renames
sweeping route-tree restructures across many pages
introducing SSR/manual server rendering where the repo was SPA-only
large auth or API-client rewrites

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

添加缺失的
```
validateSearch
```
将路由/钩子中直接的网络访问迁移至
```
services/
```
目录
添加缺失的
```
pendingComponent
```
或
```
errorComponent
```
为涉及修改的页面创建缺失的
```
-components/
```
或
```
-hooks/
```
文件夹
添加或修正
```
tanstackRouter()
```
插件配置、路由脚手架或显式的环境变量/别名配置

未经明确论证，不得自动应用范围广泛或可能导致破坏性变更的迁移：

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

Step 4: Implementation

步骤4：开发实现

Carry these acceptance criteria into the active task:

text

- [ ] 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

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

text

- [ ] 遵循分层架构（路由层 -> 服务层 -> 外部API）
- [ ] 路由使用包含-components/和-hooks/的文件夹结构
- [ ] 使用export const Route = createFileRoute(...)声明路由
- [ ] Vite项目中未使用Start专属服务端函数API
- [ ] 搜索参数使用@tanstack/zod-adapter中的zodValidator
- [ ] 自定义钩子位于-hooks/目录且内部顺序正确
- [ ] 加载器保持公共安全和SSR安全
- [ ] Vite/路由平台配置保持显式（路由插件、路由文件、生成文件）
- [ ] 所有文件名使用短横线分隔命名
- [ ] 包含韩文块注释
- [ ] 使用箭头函数表达式并声明显式返回类型

Step 5: Post-Change Verification

步骤5：变更后验证

After writing code, verify:

Structure check: confirm each touched page still has
```
-components/
```
and
```
-hooks/
```
and no
```
-functions/
```
Export check: grep for
```
export const Route
```
Layer check: no direct
```
fetch
```
/
```
axios
```
in touched route or hook files
Convention check: no camelCase filenames, no
```
function
```
keyword declarations
Hook order check: read touched hooks and verify State -> Global -> Query -> Handlers -> Memo -> Effect
Execution check: loaders and route modules do not touch secrets, DB clients, or private env values directly
Platform check:
```
vite.config.ts
```
,
```
src/router.tsx
```
, env wiring, and generated router files remain coherent

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

结构检查：确认每个涉及修改的页面仍包含
```
-components/
```
和
```
-hooks/
```
目录，且无
```
-functions/
```
目录
导出检查：使用grep命令检查
```
export const Route
```
是否存在
分层检查：涉及修改的路由或钩子文件中无直接
```
fetch
```
/
```
axios
```
调用
约定检查：无小驼峰命名的文件，无
```
function
```
关键字声明的函数
钩子顺序检查：阅读涉及修改的钩子，验证顺序为状态 -> 全局 -> 查询 -> 处理器 -> 计算属性 -> 副作用
执行检查：加载器和路由模块未直接访问密钥、数据库客户端或私有环境变量
平台检查：
```
vite.config.ts
```
、
```
src/router.tsx
```
、环境变量配置及生成的路由文件保持一致

Quick Reference: Folder Structure

快速参考：文件夹结构

text

src/
├── routes/
│   ├── __root.tsx
│   ├── index.tsx
│   └── users/
│       ├── route.tsx          # shared layout / beforeLoad / loader
│       ├── index.tsx          # /users
│       ├── -components/
│       ├── -hooks/
│       ├── $id/
│       │   ├── index.tsx      # /users/$id
│       │   ├── -components/
│       │   └── -hooks/
│       └── -sections/         # optional for large pages
├── services/<domain>/
│   ├── schemas.ts
│   ├── queries.ts
│   └── mutations.ts
├── hooks/                     # global hooks
├── stores/
├── components/
├── config/
├── env/
├── lib/
├── src/router.tsx
└── routeTree.gen.ts           # generated, do not hand-edit

text

src/
├── routes/
│   ├── __root.tsx
│   ├── index.tsx
│   └── users/
│       ├── route.tsx          # 共享布局 / beforeLoad / 加载器
│       ├── index.tsx          # /users
│       ├── -components/
│       ├── -hooks/
│       ├── $id/
│       │   ├── index.tsx      # /users/$id
│       │   ├── -components/
│       │   └── -hooks/
│       └── -sections/         # 大型页面可选目录
├── services/<domain>/
│   ├── schemas.ts
│   ├── queries.ts
│   └── mutations.ts
├── hooks/                     # 全局钩子
├── stores/
├── components/
├── config/
├── env/
├── lib/
├── src/router.tsx
└── routeTree.gen.ts           # 自动生成文件，请勿手动编辑

Common Mistakes

常见错误

Mistake	Fix
`routes/users.tsx` for a full page	`routes/users/index.tsx`
`routes/users/$id.tsx` while the page owns its own UI/logic folders	`routes/users/$id/index.tsx`
`const Route = createFileRoute(...)`	`export const Route = createFileRoute(...)`
Direct `fetch()` in route/hook	move to `services/<domain>/queries.ts` or `mutations.ts`
`createServerFn(...)` or `useServerFn(...)` in this app	use services + TanStack Query
Page component holds `useState` , `useQuery` , mutations inline	extract to `-hooks/use-*.ts`
`routeTree.gen.ts` edited manually	regenerate it; do not hand-edit
Loader reads secrets or non- `VITE_` env values	move behind a real backend/API boundary
`validateSearch` uses raw unvalidated search	add `zodValidator(schema)`

错误	修复方案
使用 `routes/users.tsx` 作为完整页面路由	改为 `routes/users/index.tsx`
页面拥有独立UI/逻辑文件夹但使用 `routes/users/$id.tsx`	改为 `routes/users/$id/index.tsx`
声明路由时使用 `const Route = createFileRoute(...)`	改为 `export const Route = createFileRoute(...)`
路由/钩子中直接使用 `fetch()`	迁移至 `services/<domain>/queries.ts` 或 `mutations.ts`
应用中使用 `createServerFn(...)` 或 `useServerFn(...)`	使用服务层 + TanStack Query替代
页面组件中内联使用 `useState` 、 `useQuery` 、变更操作	提取至 `-hooks/use-*.ts` 文件
手动编辑 `routeTree.gen.ts`	重新生成该文件；请勿手动编辑
加载器读取密钥或非 `VITE_` 前缀的环境变量	将逻辑迁移至真实后端/API边界之后
使用搜索参数但未配置 `validateSearch`	添加 `zodValidator(schema)`

Red Flags - STOP and Fix

危险信号 - 立即停止并修复

```
@tanstack/react-start
```
is present but the Vite skill is being applied
route or hook imports
```
fetch
```
/
```
axios
```
directly
missing
```
export
```
on
```
const Route
```
page component contains inline state/query/mutation logic
```
createServerFn
```
,
```
useServerFn
```
, or
```
-functions/
```
appears in the route tree
loader or route module reads secrets, DB clients, or private env values directly
```
routeTree.gen.ts
```
has hand edits
search params are used without
```
validateSearch
```

项目中存在
```
@tanstack/react-start
```
但仍在应用Vite规则
路由或钩子直接导入
```
fetch
```
/
```
axios
```
```
const Route
```
未添加
```
export
```
页面组件包含内联状态/查询/变更逻辑
路由树中出现
```
createServerFn
```
、
```
useServerFn
```
或
```
-functions/
```
目录
加载器或路由模块直接访问密钥、数据库客户端或私有环境变量
```
routeTree.gen.ts
```
存在手动编辑痕迹
使用搜索参数但未配置
```
validateSearch
```