SuperAPI AI 工具集

start-core

前端与建站

查看项目

更新于 10-26 16:21

技能介绍

用途

start-core 是面向 TanStack Start 项目的核心搭建与接线技能,适用于三类场景:为 TanStack Start 项目搭建脚手架、配置构建工具,以及排查初始化阶段的常见问题(空白页、hydration 失败、客户端不加载 JS)。

需要明确的是:TanStack Start 是构建在 TanStack Router 与 Vite(也支持 Rsbuild)之上的全栈 React 框架,并非 Next.js。它提供 SSR、流式渲染、服务端函数(类型安全 RPC)、中间件和通用部署能力。该技能针对 @tanstack/react-start v1.168.58。

主要能力

  1. 框架差异说明:明确 Start 不使用 getServerSideProps、"use server" 指令或 app/layout.tsx;路由位于 src/routes/,仅服务端代码使用 createServerFn。
  2. 同构执行模型提示:代码默认同构,loader 在服务端和客户端都会执行;涉及执行边界问题时建议改用 start-execution-model 技能。
  3. 类型推断约束:类型完全推断,不要对已推断的值做类型断言或标注。
  4. 项目接线文件说明:每个应用需要两个手写接线文件——src/router.tsx(getRouter() 工厂,返回 createRouter({ routeTree }))与 src/routes/__root.tsx(文档外壳,包含 <html>、HeadContent、Outlet、Scripts);另有一个由插件生成的 src/routeTree.gen.ts,不可编辑。
  5. 最小配置示例:给出 vite.config.ts 示例,其中 tanstackStart() 插件必须置于 React 插件之前;以及 src/router.tsx 示例。
  6. 参考文档索引:project-setup.md(安装、Vite/Rsbuild 配置、package.json、tsconfig)、project-anatomy.md(src/ 布局、getRouter、__root.tsx、生成的路由树)、common-mistakes.md(插件顺序、缺失 <Scripts />、verbatimModuleSyntax)、templates/minimal-project.md(完整可复制的最小项目)。
  7. 脚手架快捷方式:可用 npx @tanstack/cli@latest create 创建项目,或通过 npx gitpick 克隆官方示例。

使用方式

在实现前,先依据 Context7(/websites/tanstack_start_framework_react)与 Exa 核对当前 API,再探索目标代码库;修改后运行 fuse-ai-pilot:sniper。搭建时可按最小 Vite 配置接入 tanstackStart() 与 viteReact(),创建 src/router.tsx 与 src/routes/__root.tsx,或直接使用 CLI 脚手架。

限制与禁止事项

不要把 React Vite 插件放在 tanstackStart() 之前(会破坏生成);不要编辑 src/routeTree.gen.ts;不要在 __root.tsx 中遗漏 <Scripts />(会导致无 hydration);不要启用 verbatimModuleSyntax(会使服务端代码泄漏进客户端包);不要套用 Next.js/Remix 模式(getServerSideProps、"use server")。该技能不深入讲解服务端与同构执行边界(用 start-execution-model),不涉及 SOLID/代码组织(用 solid-tanstack-start),也不适用于不带 Start 的普通 React SPA。