tanstack-start-best-practices
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTanStack Start Best Practices
TanStack Start 最佳实践
Comprehensive guidelines for implementing TanStack Start patterns in full-stack React applications. These rules cover server functions, middleware, SSR, authentication, and deployment.
为全栈React应用实现TanStack Start模式的综合指南。这些规则涵盖服务器函数、中间件、SSR、身份验证以及部署。
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
- 为数据变更创建服务器函数
- 设置用于身份验证/日志记录的中间件
- 配置SSR与水合（hydration）
- 实现身份验证流程
- 处理客户端/服务器边界的错误
- 组织全栈代码
- 部署到各类平台
Rule Categories by Priority
按优先级划分的规则类别
| Priority | Category | Rules | Impact |
|---|---|---|---|
| CRITICAL | Server Functions | 5 rules | Core data mutation patterns |
| CRITICAL | Security | 4 rules | Prevents vulnerabilities |
| HIGH | Middleware | 4 rules | Request/response handling |
| HIGH | Authentication | 4 rules | Secure user sessions |
| MEDIUM | API Routes | 1 rule | External endpoint patterns |
| MEDIUM | SSR | 6 rules | Server rendering patterns |
| MEDIUM | Error Handling | 3 rules | Graceful failure handling |
| MEDIUM | Environment | 1 rule | Configuration management |
| LOW | File Organization | 3 rules | Maintainable code structure |
| LOW | Deployment | 2 rules | Production readiness |
| 优先级 | 类别 | 规则数量 | 影响 |
|---|---|---|---|
| 关键 | 服务器函数 | 5条规则 | 核心数据变更模式 |
| 关键 | 安全 | 4条规则 | 预防漏洞 |
| 高 | 中间件 | 4条规则 | 请求/响应处理 |
| 高 | 身份验证 | 4条规则 | 安全用户会话 |
| 中 | API路由 | 1条规则 | 外部端点模式 |
| 中 | SSR | 6条规则 | 服务器渲染模式 |
| 中 | 错误处理 | 3条规则 | 优雅的故障处理 |
| 中 | 环境 | 1条规则 | 配置管理 |
| 低 | 文件组织 | 3条规则 | 可维护的代码结构 |
| 低 | 部署 | 2条规则 | 生产就绪性 |
Quick Reference
快速参考
Server Functions (Prefix: sf-
)
sf-服务器函数（前缀：sf-
）
sf-- — Use createServerFn for server-side logic
sf-create-server-fn - — Always validate server function inputs
sf-input-validation - — Choose appropriate HTTP method
sf-method-selection - — Handle errors in server functions
sf-error-handling - — Customize response headers when needed
sf-response-headers
- — 使用createServerFn实现服务器端逻辑
sf-create-server-fn - — 始终验证服务器函数的输入
sf-input-validation - — 选择合适的HTTP方法
sf-method-selection - — 处理服务器函数中的错误
sf-error-handling - — 必要时自定义响应头
sf-response-headers
Security (Prefix: sec-
)
sec-安全（前缀：sec-
）
sec-- — Validate all user inputs with schemas
sec-validate-inputs - — Protect routes with auth middleware
sec-auth-middleware - — Keep secrets server-side only
sec-sensitive-data - — Implement CSRF protection for mutations
sec-csrf-protection
- — 使用验证规则校验所有用户输入
sec-validate-inputs - — 用身份验证中间件保护路由
sec-auth-middleware - — 敏感数据仅保留在服务器端
sec-sensitive-data - — 为数据变更实现CSRF保护
sec-csrf-protection
Middleware (Prefix: mw-
)
mw-中间件（前缀：mw-
）
mw-- — Use request middleware for cross-cutting concerns
mw-request-middleware - — Use function middleware for server functions
mw-function-middleware - — Properly pass context through middleware
mw-context-flow - — Compose middleware effectively
mw-composability
- — 使用请求中间件处理横切关注点
mw-request-middleware - — 为服务器函数使用函数中间件
mw-function-middleware - — 通过中间件正确传递上下文
mw-context-flow - — 有效组合中间件
mw-composability
Authentication (Prefix: auth-
)
auth-身份验证（前缀：auth-
）
auth-- — Implement secure session handling
auth-session-management - — Protect routes with beforeLoad
auth-route-protection - — Verify auth in server functions
auth-server-functions - — Configure secure cookie settings
auth-cookie-security
- — 实现安全的会话处理
auth-session-management - — 使用beforeLoad保护路由
auth-route-protection - — 在服务器函数中验证身份
auth-server-functions - — 配置安全的Cookie设置
auth-cookie-security
API Routes (Prefix: api-
)
api-API路由（前缀：api-
）
api-- — Create API routes for external consumers
api-routes
- — 为外部消费者创建API路由
api-routes
SSR (Prefix: ssr-
)
ssr-SSR（前缀：ssr-
）
ssr-- — Load data appropriately for SSR
ssr-data-loading - — Prevent hydration mismatches
ssr-hydration-safety - — Implement streaming SSR for faster TTFB
ssr-streaming - — Apply selective SSR when beneficial
ssr-selective - — Configure static prerendering and ISR
ssr-prerender
- — 为SSR适当加载数据
ssr-data-loading - — 避免水合不匹配
ssr-hydration-safety - — 实现流式SSR以加快TTFB
ssr-streaming - — 在有益时应用选择性SSR
ssr-selective - — 配置静态预渲染和ISR
ssr-prerender
Environment (Prefix: env-
)
env-环境（前缀：env-
）
env-- — Use environment functions for configuration
env-functions
- — 使用环境函数进行配置
env-functions
Error Handling (Prefix: err-
)
err-错误处理（前缀：err-
）
err-- — Handle server function errors
err-server-errors - — Use redirects appropriately
err-redirects - — Handle not-found scenarios
err-not-found
- — 处理服务器函数错误
err-server-errors - — 合理使用重定向
err-redirects - — 处理未找到场景
err-not-found
File Organization (Prefix: file-
)
file-文件组织（前缀：file-
）
file-- — Separate server and client code
file-separation - — Use .functions.ts pattern
file-functions-file - — Share validation schemas
file-shared-validation
- — 分离服务器和客户端代码
file-separation - — 使用.functions.ts模式
file-functions-file - — 共享验证规则
file-shared-validation
Deployment (Prefix: deploy-
)
deploy-部署（前缀：deploy-
）
deploy-- — Configure environment variables
deploy-env-config - — Choose appropriate deployment adapter
deploy-adapters
- — 配置环境变量
deploy-env-config - — 选择合适的部署适配器
deploy-adapters
How to Use
使用方法
Each rule file in the directory contains:
rules/- Explanation — Why this pattern matters
- Bad Example — Anti-pattern to avoid
- Good Example — Recommended implementation
- Context — When to apply or skip this rule
rules/- 说明 — 该模式的重要性
- 反面示例 — 需要避免的反模式
- 正面示例 — 推荐的实现方式
- 适用场景 — 何时应用或跳过该规则
Full Reference
完整参考
See individual rule files in directory for detailed guidance and code examples.
rules/请查看目录下的单个规则文件，获取详细指导和代码示例。
rules/