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
| 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 | 5 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 |
Quick Reference
Server Functions (Prefix: sf-)
sf-create-server-fn— Use createServerFn for server-side logicsf-input-validation— Always validate server function inputssf-method-selection— Choose appropriate HTTP methodsf-error-handling— Handle errors in server functionssf-response-headers— Customize response headers when needed
Security (Prefix: sec-)
sec-validate-inputs— Validate all user inputs with schemassec-auth-middleware— Protect routes with auth middlewaresec-sensitive-data— Keep secrets server-side onlysec-csrf-protection— Implement CSRF protection for mutations
Middleware (Prefix: mw-)
mw-request-middleware— Use request middleware for cross-cutting concernsmw-function-middleware— Use function middleware for server functionsmw-context-flow— Properly pass context through middlewaremw-composability— Compose middleware effectively
Authentication (Prefix: auth-)
auth-session-management— Implement secure session handlingauth-route-protection— Protect routes with beforeLoadauth-server-functions— Verify auth in server functionsauth-cookie-security— Configure secure cookie settings
API Routes (Prefix: api-)
api-routes— Create API routes for external consumers
SSR (Prefix: ssr-)
ssr-data-loading— Load data appropriately for SSRssr-hydration-safety— Prevent hydration mismatchesssr-streaming— Implement streaming SSR for faster TTFBssr-selective— Apply selective SSR when beneficialssr-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 errorserr-redirects— Use redirects appropriatelyerr-not-found— Handle not-found scenarios
File Organization (Prefix: file-)
file-separation— Separate server and client codefile-functions-file— Use .functions.ts patternfile-shared-validation— Share validation schemas
Deployment (Prefix: deploy-)
deploy-env-config— Configure environment variablesdeploy-adapters— Choose appropriate deployment adapter
How to Use
Each rule file in the rules/ directory contains:
- Explanation — Why this pattern matters
- Bad Example — Anti-pattern to avoid
- Good Example — Recommended implementation
- Context — When to apply or skip this rule
Full Reference
See individual rule files in rules/ directory for detailed guidance and code examples.
