mcpField
T
tanstack-start-architecture

tanstack-start-architecture

github.com/dobroslavradosavljevic开发339 次安装2 天前更新
代码仓库

关于 tanstack-start-architecture

面向 TanStack Start 开发者的独立架构 Skill，用于搭建、扩展和审查应用代码。它规定文件位置、命名和归属，不涉及框架 API 或部署。

主要功能

  1. 01页面与路由目录约定
  2. 02UI 和 hooks 的放置规则
  3. 03可复用模块的划分指引
  4. 04搭建、应用与审查模式
  5. 05按技术栈选择扩展

适用场景

  1. 01搭建新页面或布局
  2. 02放置路由专属辅助代码与 UI
  3. 03按架构规则审查应用

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/dobroslavradosavljevic/skills --skill tanstack-start-architecture

安装后在 Claude Code 中输入/tanstack-start-architecture确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
checklist.md
examples.md
rules.md
tree.md
with-better-auth-client.md
with-client-authorization.md
with-effect.md
with-env.md
with-generated-api-client.md
with-route-gates.md
with-tanstack-form.md
with-tanstack-query.md
with-ui-package.md
with-vitest.md

详细介绍

TanStack Start 架构

适用于 TanStack Start（@tanstack/react-start）应用的可移植目录规范。单独使用此技能即可——它不依赖其他技能。

**用途：**确定 UI、钩子和功能代码的位置，以及文件夹／文件命名和所有权。

**不适用于此技能：**Start／Router API 的特性、SSR 适配器、部署或最新框架文档。请优先参考当前的 TanStack Start／Router 文档。官方 Start 文档仍将该框架描述为候选发布版（API 被认为是稳定的，但并非没有缺陷）。与其他地方过时的“alpha”标签相比，请优先使用 @tanstack/react-start 和 @tanstack/react-router 的 npm latest 版本。

如果目标仓库已有架构文档（例如 AGENTS.md）且与此处冲突，以仓库为准，除非用户要求迁移到此技能所述规范。

技术栈默认设置（核心）

部分默认设置
框架TanStack Start + 基于文件的 TanStack Router（Vite 或 Rsbuild）
入口文件src/router.tsx（getRouter）、routes/__root.tsx、生成的 routeTree.gen.ts；可选的 start.ts／server.ts
页面每个页面使用文件夹 + index.tsx（不使用扁平页面文件）
仅路由代码使用连字符前缀的同级文件夹（-components、-hooks、-lib）
可复用功能通过复用门槛后放入 src/modules/<feature>/
全应用 UIsrc/components/
非功能基础设施src/lib/
忽略前缀Router 的 routeFileIgnorePrefix 默认值为 -

当存在匹配的 *with- 扩展**时，加载这些扩展（见下文）。

模式

  1. 搭建 — 根据 checklist.md + tree.md 创建新页面／布局／功能。
  2. 应用 — 将新的 UI／钩子／辅助代码放在规范位置。
  3. 审查 — 对照 rules.md 检查；提出移动建议；不要另行发明一套目录结构。

硬性规则（核心）

  1. 每个页面都使用 segment/index.tsx。 不要添加扁平页面文件（例如将 billing.tsx 作为页面组件文件）。优先使用 billing/index.tsx。
  2. 仅路由模块使用 - 前缀（或应用配置的忽略前缀）。src/routes 下不带前缀的文件会变成 URL。
  3. 新页面 UI 默认放在 routes/…/-components。 仅页面使用的钩子放在 -hooks，辅助代码放在 -lib。
  4. **src/modules/<feature>/ 的复用门槛：**出现第二个使用方时，或存在明确需要跨路由共享的客户端／架构时，再将其移入该目录。不要预先创建空的模块目录树。
  5. 模块不得从 src/routes 导入代码。 路由可以导入模块。
  6. 默认不使用模块的汇总入口 index.ts。 导入具体路径（@/modules/billing/hooks/use-checkout）。
  7. 全应用工具包 → src/components/； 非功能基础设施 → src/lib/。不要把零散的共享 UI 堆进 routes/。
  8. 无路径段布局使用 _name/（或 _name.tsx），在不改变 URL 的情况下包装某个分区。
  9. **命名：**文件夹 = 名词／路由段；叶子文件 = 简短方面（billing-page.tsx、use-checkout.ts）。如果文件夹已经体现路径，不要在每个文件名中重复冗长的父路径。
  10. **每个路由文件夹只负责一项工作：**该路由段的页面／布局及其同级私有代码。

详情见：rules.md、tree.md、examples.md。

渐进式展开

需求阅读
规范目录树 + 约定references/tree.md
执行规则 + 反模式references/rules.md
搭建／审查清单references/checklist.md
良好与糟糕的目录布局references/examples.md
可选技术栈覆盖项下方的 Extensions

扩展

仅当存在匹配的技术栈（或用户提出要求）时，才加载扩展。 扩展会添加规则；不会替代核心目录树。

适用情况扩展
生成的 OpenAPI / Hey 风格客户端with-generated-api-client.md
Better Auth（或会话）客户端模块with-better-auth-client.md
TanStack Query + loaders / queryClient.querywith-tanstack-query.md
无路径认证 / 引导流程 / 组织门控with-route-gates.md
TanStack Form + 模块/路由架构with-tanstack-form.md
T3 Env / VITE_ 客户端密钥with-env.md
纯授权包 + 客户端适配器with-client-authorization.md
工作区 UI 包 + Storybook/设计令牌with-ui-package.md
Effect Schema / 仅限服务端的 Effectwith-effect.md
Vitest — 侧重 libs/schemas/gateswith-vitest.md

评论

支持 Markdown