gh-greyhaven-ai-claude-code-config-grey-haven-plugins-research/skills/tanstack-patterns/checklists/tanstack-checklist.md

TanStack Patterns Checklist

Use before creating PR for TanStack Start/Router/Query code.

TanStack Router

• File structure follows conventions (__root.tsx, _layout.tsx, $param.tsx)
• Root route includes QueryClient provider
• Protected routes use beforeLoad for auth checks
• Loaders use loader for data fetching
• Route params are type-safe
• Navigation uses type-safe Link component
• Redirects include return URL in search params

TanStack Query

• QueryClient configured with Grey Haven defaults (staleTime: 60000)
• Query keys follow pattern: specific to general (["user", userId])
• Query keys don't include function names
• staleTime set appropriately for data type
• Error states handled in components
• Loading states handled in components
• Mutations invalidate queries after success
• Optimistic updates use onMutate and rollback on error

Server Functions

• All server functions include tenant_id parameter
• Server functions use correct HTTP method (GET/POST/DELETE)
• Multi-tenant isolation with tenant_id filtering
• Error handling with appropriate error messages
• Return types are type-safe
• Server functions used with TanStack Query hooks

Multi-Tenant

• tenant_id included in all server functions
• tenant_id included in all query keys
• useTenant() hook used for consistent tenant access
• Queries use enabled: !!tenantId guard
• RLS policies applied when using RLS pattern
• Test cases verify tenant isolation

Caching Strategy

• Auth data: 5 minutes staleTime
• User profiles: 1 minute staleTime
• Lists: 1 minute staleTime
• Static/config: 10 minutes staleTime
• Realtime: 0 staleTime (always refetch)
• Prefetching used for performance optimization

Performance

• Prefetching on hover/navigation
• Parallel queries for independent data
• Dependent queries use enabled option
• Infinite queries for pagination
• Background refetching configured appropriately

Code Quality

• Custom hooks created for reusable query logic
• Query logic separated from component logic
• Type-safe throughout (params, return types, mutations)
• DevTools enabled in development
• No console errors or warnings

Testing

• Route loaders tested
• Server functions tested
• Query hooks tested
• Mutation logic tested
• Tenant isolation tested
• Error handling tested

Documentation

• Complex query logic documented
• Custom hooks documented
• Server functions documented with JSDoc
• Route loaders documented