tanstack-start-guide

Is it a mutation (create/update/delete)? → Use server function + useMutation

Is it UI state that should be shareable? → Use search params in the URL

Is it temporary UI state (form inputs, toggles)? → Use useState/useReducer locally

Is it derived from other state? → Calculate it during render (useMemo if expensive)

Does it need to sync with external systems? → Use useEffect (this is the ONLY valid use case)

// Component just consumes data function ProductList() { const { category } = Route.useParams() const { data } = useSuspenseQuery({ queryKey: ['products', category], }) // No loading state needed - Suspense handles it }

</example>
</data-fetching-patterns>

<state-management-principles>
- Server state is not client state - don't mix them
- URL state > Context > Component state (in order of preference)
- One source of truth per piece of data
- Mutations should be optimistic by default
- Form state can be local until submission
</state-management-principles>

<server-functions>
<rule>
<name>Server functions for all mutations and server-only logic</name>
<why>Type-safe RPC, automatic validation, progressive enhancement</why>
<requirements>
- Always validate inputs with schemas
- Return meaningful responses for optimistic updates
- Handle both FormData (no-JS) and JSON submissions
- Never expose sensitive operations to client bundles
</requirements>
</rule>
</server-functions>

<react-patterns>
- Components are pure functions - no side effects during render
- Effects are escape hatches, not go-to solutions
- Suspense boundaries at route level for best streaming
- Error boundaries colocated with Suspense boundaries
- Prefer composition over prop drilling or context
- CSS handles animations, not JavaScript state machines
</react-patterns>

<performance-guidelines>
- Code splits at route boundaries automatically
- Lazy load below-the-fold components
- Preload likely next navigations
- Stream HTML as soon as possible
- Keep client bundles small for edge deployment
- Use platform capabilities (KV, R2) over custom solutions
</performance-guidelines>

<type-safety-requirements>
- Every route param must be validated
- Search params need schema validation
- Server function inputs/outputs fully typed
- No `any` types in route definitions
- Leverage inference over explicit types
</type-safety-requirements>