|
History
|
||
|---|---|---|
| .. | ||
| README.md | ||
| use-environment-variables.md | ||
| write-isomorphic-client-server-code.md | ||
How-To Guides for TanStack Start
This directory contains focused, step-by-step instructions for common TanStack Start tasks. Each guide is designed to be:
- Task-focused: Covers one specific goal from start to finish
- Self-contained: All necessary steps included, no prerequisites assumed
- Copy-paste ready: Working code examples you can use immediately
- Problem-solving oriented: Addresses real-world scenarios and common issues
Implementation Plan - Sorted by First-Principles & Dependencies
Based on GitHub issues analysis and actual user pain points from the TanStack/router repository
Foundation Layer (Prerequisites for everything else)
1. How to Write Isomorphic, Client-Only, and Server-Only Code
Priority: Foundation | Dependencies: None | Status: ✅ Completed
Core concept that affects every subsequent pattern in TanStack Start.
Should Cover:
- Understanding the execution boundary (server vs client)
- Code organization strategies for different execution contexts
- Common pitfalls and how to avoid them
- When to use each pattern
2. How to Create Basic Server Functions
Priority: Foundation | Dependencies: #1 | Status: 📝 Needed
GitHub Issues: #4533 (TypeScript issues)
Core server function concepts before advanced patterns.
Should Cover:
createServerFn()basic setup and usage- Input validation with validators (Zod, Valibot)
- Return types and serialization
- Error handling patterns
- Basic HTTP methods (GET, POST)
- Calling server functions from client components
3. How to Write Type-Safe Server Functions
Priority: Critical | Dependencies: #2 | Status: 🔥 Urgent
GitHub Issues: #4533 (5 👍)
Should Cover:
- Designing server functions with proper TypeScript patterns
- Avoiding "Type instantiation is excessively deep" errors
- Structuring types to prevent recursive type issues
- Input/output type validation patterns
- Performance-optimized TypeScript configurations
- Testing type safety in server functions
Server Function Advanced Patterns
4. How to Use Server Function Middleware
Priority: Foundation | Dependencies: #2 | Status: 📝 Needed
GitHub Issues: #4737, #4738, #4460
Should Cover:
createMiddleware()setup and patterns- Proper
next()calling patterns (avoid multiple calls) - Composing multiple middleware functions
- Authentication middleware patterns
- Logging and observability middleware
- Error handling middleware
- Conditional middleware application
5. How to Handle Redirects in Server Functions
Priority: High | Dependencies: #4 | Status: 🔥 Urgent
GitHub Issues: #4460 (5 👍)
Should Cover:
- Redirect patterns with and without middleware
- Why redirects fail with middleware
- Proper response handling
- Authentication redirect patterns
- Common redirect failures and solutions
6. How to Manage Server Function Context
Priority: Core | Dependencies: #4 | Status: 📝 Needed
Should Cover:
- Context creation and typing
- Passing context between middleware layers
- Request context (headers, cookies, user info)
- Database connections in context
- Context inheritance patterns
- Performance considerations
7. How to Use sendContext for Server-Client Communication
Priority: Core | Dependencies: #6 | Status: 📝 Needed
Should Cover:
sendContextAPI usage and patterns- Serialization considerations
- Client-side context consumption
- Type safety with context transfer
- Performance optimization
- Use cases and best practices
Deployment & Hosting Layer (Major User Pain Points)
8. How to Deploy to Cloudflare Pages/Workers (Comprehensive)
Priority: Critical | Dependencies: #2 | Status: 🔥 Urgent
GitHub Issues: #4473 (13 👍), #4400
Should Cover:
- Cloudflare Pages deployment setup
- Cloudflare Workers configuration
@cloudflare/vite-pluginintegration- Wrangler.toml configuration (best practices)
- Post-vinxi→vite migration fixes
- Virtual imports (
cloudflare:workflows,cloudflare:workers) - Environment variable management
- Custom Nitro configuration for Cloudflare
- Note: Some plugin configuration issues (#4779) are upstream dependencies
9. How to Deploy to Netlify
Priority: High | Dependencies: #2 | Status: 📝 Needed
Partnership Focus: Netlify (official hosting partner)
Should Cover:
- Netlify-specific configuration
- Edge functions integration
- Environment variables
- Build optimization
- Server function deployment on Netlify
10. How to Deploy to Netlify with Clerk Integration
Priority: High | Dependencies: #9 | Status: 📝 Needed
GitHub Issues: #4762
Should Cover:
- Netlify + Clerk webhook setup
- Authentication flow on Netlify
- Environment variable management
- Edge function auth patterns
- Troubleshooting common issues
11. How to Deploy to Vercel
Priority: Medium-High | Dependencies: #2 | Status: 📝 Needed
Should Cover:
- Vercel Edge Functions
- Serverless function optimization
- Build configuration
- Performance monitoring
Advanced Configuration & Troubleshooting
12. How to Configure Custom Nitro Settings
Priority: Medium-High | Dependencies: #8 | Status: 📝 Needed
GitHub Issues: #4404 (3 👍)
Should Cover:
- Post-vinxi→vite migration Nitro configuration
- Custom deployment target settings
- Advanced Nitro options for different platforms
- Migration troubleshooting from old configs
tanstackStart({ nitro: { ... } })patterns
13. How to Handle Deferred Data and Streaming
Priority: High | Dependencies: #2 | Status: 📝 Needed
GitHub Issues: #4802
Should Cover:
- Deferred data patterns in Start
- Server vs client promise resolution
- Page refresh behavior with deferred data
- Streaming best practices
useSuspenseQuerywith server functions- Dynamic streaming without configuration
14. How to Handle URL Parameters and Encoding
Priority: Medium-High | Dependencies: #1 | Status: 📝 Needed
GitHub Issues: #4514
Should Cover:
- Encoded URL parameter handling
- Preventing redirect loops on page refresh
- Complex parameter validation
- URL encoding best practices
- Client vs server parameter handling
15. How to Configure Project Structure and srcDirectory
Priority: Medium | Dependencies: #1 | Status: 📝 Needed
GitHub Issues: #4432
Should Cover:
- srcDirectory configuration options
- Root directory setup patterns
- Avoiding "Invalid lazy handler" errors
- Project structure best practices
- File organization strategies
Server Infrastructure Layer
16. How to Create and Configure Server Routes
Priority: Core | Dependencies: #2 | Status: 📝 Needed
Should Cover:
- Server route file conventions
- HTTP method handling with server functions
- Route parameters and server function integration
- Middleware integration with server routes
- Error handling patterns
17. How to Implement Single Flight Mutations with TanStack Query
Priority: Medium-High | Dependencies: #2, #7 | Status: 📝 Needed
Advanced Pattern: Server function + TanStack Query optimization
Should Cover:
- Single flight mutation patterns
- Server function integration with TanStack Query
- Optimistic updates with server functions
- Error handling and rollback strategies
- Performance optimization techniques
- Cache invalidation patterns
Database & Partnership Integrations
18. How to Set Up TanStack DB with Start
Priority: High | Dependencies: #6, #7 | Status: 📝 Needed
TanStack Ecosystem Integration
Should Cover:
- TanStack DB setup and configuration
- Database context in server functions
- Type-safe database operations
- Migration patterns with Start
- Real-time features integration
- Performance optimization patterns
19. How to Set Up Neon Database Integration
Priority: High | Dependencies: #6 | Status: 📝 Needed
Partnership Focus: Neon (sponsor)
Should Cover:
- Neon setup with server function context
- Connection pooling in middleware
- Serverless-optimized patterns
- Environment management
- Migration workflows
20. How to Integrate with Convex
Priority: High | Dependencies: #6, #13 | Status: 📝 Needed
Partnership Focus: Convex (sponsor) + Real-time
Should Cover:
- Convex integration with server functions
- Real-time data with sendContext
- Authentication integration patterns
- Convex mutations vs server functions
- Performance optimization
Server Framework Integrations
21. How to Integrate tRPC with TanStack Start
Priority: High | Dependencies: #16 | Status: 📝 Needed
Should Cover:
- tRPC router setup in server routes
- tRPC vs server functions comparison
- Hybrid patterns (when to use each)
- Authentication middleware with tRPC
- Type-safe client integration
22. How to Use Hono with TanStack Start
Priority: Medium-High | Dependencies: #16 | Status: 📝 Needed
Should Cover:
- Hono app integration in server routes
- Hono middleware vs Start middleware
- Performance optimizations
- Edge runtime compatibility
Authentication & Authorization
23. How to Implement Full-Stack Authentication (Comprehensive)
Priority: Core | Dependencies: #4, #6 | Status: 📝 Needed
Should Cover:
- HTTP-Only Cookie Sessions with server function middleware
- JWT Patterns using context management
- Session Management APIs with TanStack Start
- Route Protection using middleware patterns
- Auth Context management across server functions
- Login/Logout flows with server function patterns
24. How to Integrate with Clerk Authentication
Priority: Core | Dependencies: #23 | Status: 📝 Needed
Partnership Focus: Clerk integration
Should Cover:
- Clerk middleware for server functions
- Authentication context with Clerk
- Protected server function patterns
- User management through server functions
25. How to Integrate with Better Auth
Priority: Medium | Dependencies: #23 | Status: 📝 Needed
Emerging Auth Solution
Should Cover:
- Better Auth setup and configuration
- Integration with Start's server functions
- Session management patterns
- Social login integration
Implementation Priority & Timeline
Phase 1: Critical Foundation (Immediate - 4 weeks)
- #1 - Isomorphic/Client/Server Code Boundaries ✅
- #2 - Basic Server Functions
- #3 - Write Type-Safe Server Functions 🔥
- #4 - Server Function Middleware
- #5 - Handle Redirects in Server Functions 🔥
Phase 2: Deployment Blockers (6 weeks)
- #8 - Cloudflare Deployment (Comprehensive) 🔥
- #9 - Netlify Deployment
- #10 - Netlify + Clerk Integration
- #12 - Custom Nitro Configuration
Phase 3: Advanced Server Patterns (8 weeks)
- #6 - Server Function Context Management
- #7 - sendContext Usage
- #13 - Deferred Data and Streaming
- #16 - Server Routes Configuration
- #17 - Single Flight Mutations
Phase 4: Database & Partnerships (10 weeks)
- #18 - TanStack DB Integration
- #19 - Neon Database Integration
- #20 - Convex Integration
- #21 - tRPC Integration
Phase 5: Authentication & Advanced (12 weeks)
- #23 - Full-Stack Authentication
- #24 - Clerk Integration
- #11 - Vercel Deployment
- #22 - Hono Integration
Success Metrics
Each Guide Must Include:
- Completeness: Setup to production deployment
- Working Examples: Copy-paste ready code
- Troubleshooting: Address common pitfalls and errors
- GitHub Issue Resolution: Link to and solve specific reported issues
- Next Steps: Related guides and advanced topics
Format Consistency:
- Quick Start section with minimal working example
- Step-by-step implementation with code samples
- Common Problems section addressing GitHub issues
- Production Checklist for deployment readiness
- Related Resources linking to other guides
Available Guides
- ✅ Write Isomorphic, Client-Only, and Server-Only Code - Understand execution boundaries and control where code runs in TanStack Start applications
- ✅ Use Environment Variables - Set up and use environment variables securely in TanStack Start applications
GitHub Issues Tracking
High Priority Issues to Address:
- #4533 - Server Function TypeScript Issues (5 👍)
- #4473 - Cloudflare Vite Plugin Support (13 👍)
- #4460 - Redirects in Server Functions (5 👍)
- #4779 - Cloudflare Hosting Docs
- #4762 - Netlify + Clerk Integration
- #4802 - Deferred Data Behavior
- #4737 - Server Function Middleware Patterns
- #4514 - URL Parameter Encoding
- #4432 - Project Structure Configuration
- #4404 - Custom Nitro Configuration
Contributing
When adding new how-to guides:
- Focus on a single, well-defined task
- Address specific GitHub issues when possible
- Use clear headings and numbered steps
- Include complete, working code examples
- Address the most frequent problems at the end
- Follow the dependency order outlined above
- Link to related guides and GitHub issues
Priority should be given to guides that:
- Solve actual user problems (GitHub issues)
- Enable TanStack Start's unique features (server functions)
- Support partnership integrations (Neon, Convex, Clerk, Netlify)
- Unblock deployment and production usage