grey-haven-tanstack-patterns

# Grey Haven TanStack Patterns

Follow Grey Haven Studio's patterns for TanStack Start, Router, and Query in React 19 applications.

## TanStack Stack Overview

Grey Haven uses the complete TanStack ecosystem:
- **TanStack Start**: Full-stack React framework with server functions
- **TanStack Router**: Type-safe file-based routing with loaders
- **TanStack Query**: Server state management with caching
- **TanStack Table** (optional): Data grids and tables
- **TanStack Form** (optional): Type-safe form handling

## Critical Patterns

### 1. File-Based Routing Structure

```
src/routes/
├── __root.tsx              # Root layout (wraps all routes)
├── index.tsx               # Homepage (/)
├── _authenticated/         # Protected routes group (underscore prefix)
│   ├── _layout.tsx        # Auth layout wrapper
│   ├── dashboard.tsx      # /dashboard
│   └── settings/
│       └── index.tsx      # /settings
└── users/
    ├── index.tsx          # /users
    └── $userId.tsx        # /users/:userId (dynamic param)
```

**Key conventions**:
- `__root.tsx` - Root layout with QueryClient provider
- `_authenticated/` - Protected route groups (underscore prefix)
- `_layout.tsx` - Layout wrapper for route groups
- `$param.tsx` - Dynamic route parameters

### 2. TanStack Query Defaults

```typescript
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60000, // 1 minute default
      retry: 1,
      refetchOnWindowFocus: false,
    },
  },
});
```

### 3. Query Key Patterns

```typescript
// ✅ CORRECT - Specific to general
queryKey: ["user", userId]
queryKey: ["users", { tenantId, page: 1 }]
queryKey: ["organizations", orgId, "teams"]

// ❌ WRONG
queryKey: [userId]                    // Missing resource type
queryKey: ["getUser", userId]        // Don't include function name
queryKey: [{ id: userId }]           // Object first is confusing
```

### 4. Server Functions with Multi-Tenant

```typescript
// ALWAYS include tenant_id parameter
expor