kever/epic-start-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6b9acdfc1bbe462920b3e98d341e808c553d49ed
epic-start-ui/AGENTS.md
kever 46796b5918 chore: initialize frontend project
2026-06-07 12:57:41 +08:00

11 KiB
Raw Blame History

Skill mappings - load use with pnpm dlx @tanstack/intent@latest load <use>.

skills:

  • when: "Install TanStack Devtools, pick framework adapter (React/Vue/Solid/Preact), register plugins via plugins prop, configure shell (position, hotkeys, theme, hideUntilHover, requireUrlFlag, eventBusConfig). TanStackDevtools component, defaultOpen, localStorage persistence." use: "@tanstack/devtools#devtools-app-setup"
  • when: "Publish plugin to npm and submit to TanStack Devtools Marketplace. PluginMetadata registry format, plugin-registry.ts, pluginImport (importName, type), requires (packageName, minVersion), framework tagging, multi-framework submissions, featured plugins." use: "@tanstack/devtools#devtools-marketplace"
  • when: "Build devtools panel components that display emitted event data. Listen via EventClient.on(), handle theme (light/dark), use @tanstack/devtools-ui components. Plugin registration (name, render, id, defaultOpen), lifecycle (mount, activate, destroy), max 3 active plugins. Two paths: Solid.js core with devtools-ui for multi-framework support, or framework-specific panels." use: "@tanstack/devtools#devtools-plugin-panel"
  • when: "Handle devtools in production vs development. removeDevtoolsOnBuild, devDependency vs regular dependency, conditional imports, NoOp plugin variants for tree-shaking, non-Vite production exclusion patterns." use: "@tanstack/devtools#devtools-production"
  • when: "Two-way event patterns between devtools panel and application. App-to-devtools observation, devtools-to-app commands, time-travel debugging with snapshots and revert. structuredClone for snapshot safety, distinct event suffixes for observation vs commands, serializable payloads only." use: "@tanstack/devtools-event-client#devtools-bidirectional"
  • when: "Create typed EventClient for a library. Define event maps with typed payloads, pluginId auto-prepend namespacing, emit()/on()/onAll()/onAllPluginEvents() API. Connection lifecycle (5 retries, 300ms), event queuing, enabled/disabled state, SSR fallbacks, singleton pattern. Unique pluginId requirement to avoid event collisions." use: "@tanstack/devtools-event-client#devtools-event-client"
  • when: "Analyze library codebase for critical architecture and debugging points, add strategic event emissions. Identify middleware boundaries, state transitions, lifecycle hooks. Consolidate events (1 not 15), debounce high-frequency updates, DRY shared payload fields, guard emit() for production. Transparent server/client event bridging." use: "@tanstack/devtools-event-client#devtools-instrumentation"
  • when: "Configure @tanstack/devtools-vite for source inspection (data-tsd-source, inspectHotkey, ignore patterns), console piping (client-to-server, server-to-client, levels), enhanced logging, server event bus (port, host, HTTPS), production stripping (removeDevtoolsOnBuild), editor integration (launch-editor, custom editor.open). Must be FIRST plugin in Vite config. Vite ^6 || ^7 only." use: "@tanstack/devtools-vite#devtools-vite-plugin"
  • when: "Step-by-step migration from Next.js App Router to TanStack Start: route definition conversion, API mapping, server function conversion from Server Actions, middleware conversion, data fetching pattern changes." use: "@tanstack/react-start#lifecycle/migrate-from-nextjs"
  • when: "React bindings for TanStack Start: createStart, StartClient, StartServer, React-specific imports, re-exports from @tanstack/react-router, full project setup with React, useServerFn hook." use: "@tanstack/react-start#react-start"
  • when: "Implement, review, debug, and refactor TanStack Start React Server Components in React 19 apps. Use when tasks mention @tanstack/react-start/rsc, renderServerComponent, createCompositeComponent, CompositeComponent, renderToReadableStream, createFromReadableStream, createFromFetch, Composite Components, React Flight streams, loader or query owned RSC caching, router.invalidate, structuralSharing: false, selective SSR, stale names like renderRsc or .validator, or migration from Next App Router RSC patterns. Do not use for generic SSR or non-TanStack RSC frameworks except brief comparison." use: "@tanstack/react-start#react-start/server-components"
  • when: "Framework-agnostic core concepts for TanStack Router: route trees, createRouter, createRoute, createRootRoute, createRootRouteWithContext, addChildren, Register type declaration, route matching, route sorting, file naming conventions. Entry point for all router skills." use: "@tanstack/router-core#router-core"
  • when: "Route protection with beforeLoad, redirect()/throw redirect(), isRedirect helper, authenticated layout routes (_authenticated), non-redirect auth (inline login), RBAC with roles and permissions, auth provider integration (Auth0, Clerk, Supabase), router context for auth state." use: "@tanstack/router-core#router-core/auth-and-guards"
  • when: "Automatic code splitting (autoCodeSplitting), .lazy.tsx convention, createLazyFileRoute, createLazyRoute, lazyRouteComponent, getRouteApi for typed hooks in split files, codeSplitGroupings per-route override, splitBehavior programmatic config, critical vs non-critical properties." use: "@tanstack/router-core#router-core/code-splitting"
  • when: "Route loader option, loaderDeps for cache keys, staleTime/gcTime/ defaultPreloadStaleTime SWR caching, pendingComponent/pendingMs/ pendingMinMs, errorComponent/onError/onCatch, beforeLoad, router context and createRootRouteWithContext DI pattern, router.invalidate, Await component, deferred data loading with unawaited promises." use: "@tanstack/router-core#router-core/data-loading"
  • when: "Link component, useNavigate, Navigate component, router.navigate, ToOptions/NavigateOptions/LinkOptions, from/to relative navigation, activeOptions/activeProps, preloading (intent/viewport/render), preloadDelay, navigation blocking (useBlocker, Block), createLink, linkOptions helper, scroll restoration, MatchRoute." use: "@tanstack/router-core#router-core/navigation"
  • when: "notFound() function, notFoundComponent, defaultNotFoundComponent, notFoundMode (fuzzy/root), errorComponent, CatchBoundary, CatchNotFound, isNotFound, NotFoundRoute (deprecated), route masking (mask option, createRouteMask, unmaskOnReload)." use: "@tanstack/router-core#router-core/not-found-and-errors"
  • when: "Dynamic path segments (paramName), splat routes ( / _splat), optional params ({-$paramName}), prefix/suffix patterns ({$param}.ext), useParams, params.parse/stringify, pathParamsAllowedCharacters, i18n locale patterns." use: "@tanstack/router-core#router-core/path-params"
  • when: "validateSearch, search param validation with Zod/Valibot/ArkType adapters, fallback(), search middlewares (retainSearchParams, stripSearchParams), custom serialization (parseSearch, stringifySearch), search param inheritance, loaderDeps for cache keys, reading and writing search params." use: "@tanstack/router-core#router-core/search-params"
  • when: "Non-streaming and streaming SSR, RouterClient/RouterServer, renderRouterToString/renderRouterToStream, createRequestHandler, defaultRenderHandler/defaultStreamHandler, HeadContent/Scripts components, head route option (meta/links/styles/scripts), ScriptOnce, automatic loader dehydration/hydration, memory history on server, data serialization, document head management." use: "@tanstack/router-core#router-core/ssr"
  • when: "Full type inference philosophy (never cast, never annotate inferred values), Register module declaration, from narrowing on hooks and Link, strict:false for shared components, getRouteApi for code-split typed access, addChildren with object syntax for TS perf, LinkProps and ValidateLinkOptions type utilities, as const satisfies pattern." use: "@tanstack/router-core#router-core/type-safety"
  • when: "TanStack Router bundler plugin for route generation and automatic code splitting. Supports Vite, Webpack, Rspack, and esbuild. Configures autoCodeSplitting, routesDirectory, target framework, and code split groupings." use: "@tanstack/router-plugin#router-plugin"
  • when: "Programmatic route tree building as an alternative to filesystem conventions: rootRoute, index, route, layout, physical, defineVirtualSubtreeConfig. Use with TanStack Router plugin's virtualRouteConfig option." use: "@tanstack/virtual-file-routes#virtual-file-routes"

项目上下文：my-tanstack-app (BFF + Go 后端版本)

项目初始化信息

  • 脚手架命令： npx @tanstack/cli@latest create my-tanstack-app --agent --tailwind --add-ons tanstack-query
  • 模板类型： Blank 纯净模板。
  • 技术栈方案： TanStack Start (React 19), TanStack Query, Tailwind CSS, pnpm.
  • 部署目标： 自建云服务器 (VPS)，运行于标准的 Node.js 环境。

核心架构决策

  1. BFF 架构分层： 本项目作为无状态的 Web 渲染与数据转发层（BFF）。不包含任何数据库（MySQL）驱动与凭证，不直接操作底层数据。
  2. 异构系统数据消费： 前端或服务端渲染所需的一切核心业务数据，均通过网络请求（HTTP/RESTful）异步调用自主部署的 Go 语言后端服务。
  3. 数据流控制： 路由级的数据预取优先在 loader 中通过 TanStack Query 执行，利用 dehydrate / hydrate 机制确保 SSR 数据无缝传递至客户端。

环境变量要求 (.env)

在 VPS 生产环境及本地开发环境中配置：

  • NODE_ENV: production 或 development
  • PORT: 3000 (前端服务运行端口)
  • GO_BACKEND_URL: http://127.0.0.1:8080 (指向你自建的 Go 后端服务的内部/外部基准地址)

部署与运维笔记

  • 打包模式： 修改 app.config.ts 中的 target 预设为 node（基于 Nitro 引擎进行 Node 兼容构建）。
  • 运行机制： 产物通过 node 或 pm2 在 VPS 上独立拉起进程。建议在前端挂载 Nginx 负责 443 端口 SSL 证书卸载与静态资源（.js, .css）的高效分发。

踩坑与注意点 (Known Gotchas)

  • 跨域与内网穿透： 在 SSR 阶段，Node.js 发起请求的源是服务器本身（需通过 process.env.GO_BACKEND_URL 访问内网）；在客户端阶段，浏览器发起请求需要能够跨域或通过反向代理正确路由到 Go 服务上。推荐在 Node 侧统一使用 createServerFn 做一层 API Proxy 转发。

后续推进计划

  • 确保 app.config.ts 已切换为 node 独立运行预设。
  • 运行 pnpm install 冻结当前依赖树。
  • 封装 src/utils/api.ts 统一劫持 GO_BACKEND_URL。
  • 在 src/routes/index.tsx 的 loader 中，编写第一个通过 TanStack Query 获取 Go 后端商品或任务列表的接口。