tanstack-start-best-practices

# 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 | 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 | ## Quick Reference ### Server Functions (Prefix: `sf-`) - `sf-create-server-fn` — Use createServerFn for server-side logic - `sf-input-validation` — Always validate server function inputs - `sf-method-selection` — Choose appropriate HTTP method - `sf-error-handling` — Handle errors in server functions - `sf-response-headers` — Customize response headers when needed ### Security (Prefix: `sec-`) - `sec-validate-inputs` — Validate all user inputs with schemas - `sec-auth-middleware` — Protect routes with auth middleware - `sec-sensitive-data` — Keep secrets server-side only - `sec-csrf-protection` — Implement CSRF protection for mutations ### Middleware (Prefix: `mw-`) - `mw-request-middleware` — Use request middleware for cross-cutting concerns - `mw-function-middleware` — Use function middleware for server functions - `mw-context-flow` — Properly pass context through middleware - `mw-composability` — Compose middleware effectively ### Authentication (Prefix: `auth-`) - `auth-session-management` — Implement secure session handling - `auth-route-protection` — Protect routes with beforeLoad - `auth-server-functions` — Verify auth in server functions - `auth-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 SSR - `ssr-hydration-safety` — Prevent hydration mismatches - `ssr-streaming` — Implement streaming SSR for faster TTFB - `ssr-selective` — Apply selective SSR when beneficial - `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 - `err-redirects` — Use redirects appropriately - `err-not-found` — Handle not-found scenarios ### File Organization (Prefix: `file-`) - `file-separation` — Separate server and client code - `file-functions-file` — Use .functions.ts pattern - `file-shared-validation` — Share validation schemas ### Deployment (Prefix: `deploy-`) - `deploy-env-config` — Configure environment variables - `deploy-adapters` — Choose appropriate deployment adapter ## 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.