mcpField
T
tanstack-start-conventions

tanstack-start-conventions

github.com/fixmyberlin开发051 次安装今天更新
代码仓库

关于 tanstack-start-conventions

为使用 TanStack Start 构建或重构应用的团队提供约定指南，按任务组织参考内容，并规定服务端边界、服务端函数和 SSR 做法。使用时需要配合 tanstack-router-conventions 技能。

主要功能

  1. 01按任务分类的参考指南
  2. 02客户端与服务端边界规则
  3. 03服务端函数约定
  4. 04路由 SSR 指南
  5. 05API 路由验证规则

适用场景

  1. 01搭建或重构应用目录
  2. 02确定服务端代码的放置位置
  3. 03实现经过验证的服务端函数
  4. 04配置路由渲染行为

安装

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

$npx skills add https://github.com/fixmyberlin/fixmyskills --skill tanstack-start-conventions

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

包含的文件

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

references/
app-structure.md
client-server-boundaries.md
execution-model.md
local-runtime.md
params-search-api-routes.md
selective-ssr.md
server-components.md
server-functions.md

详细介绍

TanStack Start 约定

本组织中 TanStack Start 应用的技术栈约定。需要使用 skill tanstack-router-conventions（搜索参数、美观 URL、loader + Query、表单与 useMutation、类型安全的 Router TS、开发工具）——此处不重复说明。身份验证和会话布局请搭配使用 tanstack-start-auth。

应阅读的参考文档

任务文件
搭建或重构 app/src 文件夹、精简路由、Layout/Page 命名、测试app-structure.md
在 .server.ts / .functions.ts 之间拆分代码、导入保护、beforeLoad 与 loader 的取舍、错误日志记录client-server-boundaries.md
编写 createServerFn、验证、表单提交、失效处理server-functions.md
Loader 或组件访问 DB/fs/机密信息、客户端导航问题execution-model.md
设置路由 ssr、调试 SSR / hydration、Query 脱水selective-ssr.md
routes/api/ 下的 API 路由（路径参数、搜索参数、POST 请求体）params-search-api-routes.md
实验性 RSC（renderServerComponent、createCompositeComponent）server-components.md
为 Vite + Nitro 脚本使用 bun --bunlocal-runtime.md

身份验证流程：skill tanstack-start-auth。

不可妥协的规则

主题规则
仅限服务端的模块*.server.ts - 绝不能由路由/组件导入（例外：routes/api/ 和没有组件的仅处理器路由）；在其中使用 createServerOnlyFn
可从客户端调用使用 createServerFn 的 *.functions.ts；导出名称以 *Fn 结尾
公开的服务端函数public*.functions.ts - 不使用全局身份验证中间件；在 .server.ts 中进行速率限制/令牌检查（参见 tanstack-start-auth）
API 路由文件路由文件上不加 server-only 导入标记；将仅限服务端的逻辑放在处理器内，或放在经过树摇优化的导入中
API 搜索参数API 路由不使用 validateSearch；在 GET 中从 request.url 使用 Zod safeParse，失败时返回 400 JSON
SSR每个路由都要显式设置 ssr；UI 默认值为 true；仅处理器 API 路由设为 false；地图密集型 UI 设为 'data-only'
本地 Bun 运行时Vite dev 和 Nitro start/preview 使用 bun --bun
路由器搜索 / Query由 tanstack-router-conventions 负责（parseSearch / stringifySearch、loader + Query）

快速决策

  • beforeLoad 与 loader： 在 beforeLoad 中处理重定向、身份验证和轻量级上下文（而非中间件）；在 loader 中获取数据 / 预热 Query。beforeLoad 会在每次导航时重新运行，包括搜索参数变更，因此对于高频路由（地图视口、图层切换），应将重定向/身份验证/区域逻辑放在 loader 中，并将这些参数排除在 loaderDeps 之外。详情：client-server-boundaries.md。
  • Loader 与 Query、表单与 mutation： 遵循 tanstack-router-conventions -> references/router-and-query.md（#client-mutations）。在 Start 中，loader 和 mutationFn 会调用 *Fn；服务端 I/O 始终通过 createServerFn 进行。
  • ssr： 需要服务端身份验证/数据的地图/画布密集型 UI -> 'data-only'；仅处理器 API（server.handlers）-> false；完全以客户端为先的 UI 路由 -> false（少见）。
  • 服务端组件： 选择启用的实验性功能，不是默认的 FMC 数据路径。

相关技能

主题技能
路由器（必需）tanstack-router-conventions
身份验证 / 会话tanstack-start-auth
Bun 安装 / nvmtech-stack -> bun-install
Zustandzustand-state-management
不使用 TanStack Router 的 URL 状态nuqs
重构后残留代码的放置位置unslop-code Phase 6 -> references/component-location.md

评论

支持 Markdown