AgentSkillsCN

tanstack-start-best-practices

掌握TanStack Start在全栈React应用中的最佳实践。包括服务器函数、中间件、SSR、认证机制与部署模式。在使用TanStack Start构建全栈应用时启用此技能。

SKILL.md
--- frontmatter
name: tanstack-start-best-practices
description: TanStack Start best practices for full-stack React applications. Server functions, middleware, SSR, authentication, and deployment patterns. Activate when building full-stack apps with TanStack Start.

TanStack Start Best Practices

Comprehensive guidelines for implementing TanStack Start patterns in full-stack React applications. These rules cover server functions, middleware, SSR, authentication, and deployment.

When to Apply

  • •Creating server functions for data mutations
  • •Setting up middleware for auth/logging
  • •Configuring SSR and hydration
  • •Implementing authentication flows
  • •Handling errors across client/server boundary
  • •Organizing full-stack code
  • •Deploying to various platforms

Rule Categories by Priority

PriorityCategoryRulesImpact
CRITICALServer Functions2 rulesCore data mutation patterns
HIGHMiddleware1 ruleRequest/response handling
HIGHAuthentication2 rulesSecure user sessions
MEDIUMAPI Routes1 ruleExternal endpoint patterns
MEDIUMSSR3 rulesServer rendering patterns
MEDIUMError Handling1 ruleGraceful failure handling
MEDIUMEnvironment1 ruleConfiguration management
LOWFile Organization1 ruleMaintainable code structure
LOWDeployment1 ruleProduction readiness

Quick Reference

Server Functions (Prefix: sf-)

  • •sf-create-server-fn — Use createServerFn for server-side logic
  • •sf-input-validation — Always validate server function inputs

Middleware (Prefix: mw-)

  • •mw-request-middleware — Use request middleware for cross-cutting concerns

Authentication (Prefix: auth-)

  • •auth-session-management — Implement secure session handling
  • •auth-route-protection — Protect routes with beforeLoad

API Routes (Prefix: api-)

  • •api-routes — Create API routes for external consumers

SSR (Prefix: ssr-)

  • •ssr-hydration-safety — Prevent hydration mismatches
  • •ssr-streaming — Implement streaming SSR for faster TTFB
  • •ssr-prerender — Configure static prerendering and ISR

Environment (Prefix: env-)

  • •env-functions — Use environment functions for configuration

Error Handling (Prefix: err-)

  • •err-server-errors — Handle server function errors

File Organization (Prefix: file-)

  • •file-separation — Separate server and client code

Deployment (Prefix: deploy-)

  • •deploy-adapters — Choose appropriate deployment adapter

Integration Priority

When TanStack Router and TanStack Query are also present:

  • •Follow tanstack-integration/rules/precedence-query-first.md for cache ownership.
  • •Keep Query as the server-state cache authority (ensureQueryData in loaders, Query hooks in components).
  • •Use defaultPreloadStaleTime: 0 so Router defers freshness to Query.

How to Use

Each rule file in the rules/ directory contains:

  1. •Explanation — Why this pattern matters
  2. •Bad Example — Anti-pattern to avoid
  3. •Good Example — Recommended implementation
  4. •Context — When to apply or skip this rule

Full Reference

See individual rule files in rules/ directory for detailed guidance and code examples.