用途:为 TanStack Start 项目提供可移植的 src(或等价)目录布局约定,规范 React 组件、路由、服务端逻辑与测试的摆放位置。
主要能力与结构约定:顶层保持少量文件夹——components/ 放全部 React/JSX,routes/ 只放路由定义,shared/ 放同构代码(Zod schema、URL search、纯工具,不含数据库与密钥),server/ 放仅服务端文件(.server.ts、.functions.ts、QueryOptions.ts),data/ 可选放 GeoJSON、JSON 等静态资源,另有 router.tsx 等根文件。路由文件保持轻薄,导出 createFileRoute 配置(beforeLoad、loader、head、component),component 始终从 @/components/... 单次导入,不在路由内写内联组件或重型 UI,也不直接访问数据库。组件区分 Layout.tsx(路由外壳、provider、outlet)与 Page*.tsx(实际页面内容)。server/<domain>/ 下按领域组织 queries/、mutations/、.inputSchemas.ts 与 <domain>.functions.ts。URL 状态默认用路由 validateSearch(Zod)与 Route.useSearch(),router.tsx 需配置 pretty-JSON 的 parseSearch/stringifySearch 与 trailingSlash: 'never';nuqs 仅用于已使用 useQueryState 的共享或第三方组件,将 NuqsAdapter 放在所需的最小子树。搜索 schema 按需内联或放 shared。Zustand 每个关注点一个 {domain}-store.ts,仅导出自定义 hook。路由文件用文件夹归组大模块,扁平列表用点号命名。测试方面,单元/集成测试与源码同目录(Vitest),E2E 用 app 级 tests/.spec.ts(Playwright)。可选 React Email 放 src/emails/。
使用方式:按上述约定组织项目文件;涉及边界、loader、SSR 与 API 校验时参考 tanstack-start-conventions,认证参考 tanstack-start-auth。
限制:资料未提供具体安装命令、依赖版本、收费与价格信息,暂未提供。