tanstack-patterns

What this skill does

# 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
export const getUserById = createServerFn("GET", async (
  userId: string,
  tenantId: string
) => {
  const user = await db.query.users.findFirst({
    where: and(
      eq(users.id, userId),
      eq(users.tenant_id, tenantId) // Multi-tenant isolation!
    ),
  });

  if (!user) throw new Error("User not found");
  return user;
});
```

### 5. Route Loaders

```typescript
export const Route = createFileRoute("/_authenticated/dashboard")({
  // Loader fetches data on server before rendering
  loader: async ({ context }) => {
    const tenantId = context.session.tenantId;
    return await getDashboardData(tenantId);
  },
  component: DashboardPage,
});

function DashboardPage() {
  const data = Route.useLoaderData(); // Type-safe loader data
  return <div>...</div>;
}
```

### 6. Mutations with Cache Invalidation

```typescript
const mutation = useMutation({
  mutationFn: (data: UserUpdate) => updateUser(userId, data),
  // Always invalidate queries after mutation
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ["user", userId] });
  },
});
```

## Caching Strategy

Grey Haven uses these staleTime defaults:

| Data Type | staleTime | Use Case |
|-----------|-----------|----------|
| Auth data | 5 minutes | User sessions, tokens |
| User profiles | 1 minute | User details |
| Lists | 1 minute | Data tables, lists |
| Static/config | 10 minutes | Settings, configs |
| Realtime | 0 (always refetch) | Notifications |

```typescript
const STALE_TIMES = {
  auth: 5 * 60 * 1000,        // 5 minutes
  user: 1 * 60 * 1000,        // 1 minute
  list: 1 * 60 * 1000,        // 1 minute
  static: 10 * 60 * 1000,     // 10 minutes
  realtime: 0,                // Always refetch
};
```

## Supporting Documentation

All supporting files are under 500 lines per Anthropic best practices:

- **[examples/](examples/)** - Complete code examples
  - [router-patterns.md](examples/router-patterns.md) - File-based routing, layouts, navigation
  - [query-patterns.md](examples/query-patterns.md) - Queries, mutations, infinite queries
  - [server-functions.md](examples/server-functions.md) - Creating and using server functions
  - [advanced-patterns.md](examples/advanced-patterns.md) - Dependent queries, parallel queries, custom hooks
  - [INDEX.md](examples/INDEX.md) - Examples navigation

- **[reference/](reference/)** - Configuration references
  - [router-config.md](reference/router-config.md) - Router setup and configuration
  - [query-config.md](reference/query-config.md) - QueryClient configuration
  - [caching-strategy.md](reference/caching-strategy.md) - Detailed caching patterns
  - [multi-tenant.md](reference/multi-tenant.md) - Multi-tenant patterns with RLS
  - [INDEX.md](reference/INDEX.md) - Reference navigation

- **[templates/](templates/)** - Copy-paste ready templates
  - [root-route.tsx](templates/root-route.tsx) - Root layout template
  - [auth-layout.tsx](templates/auth-layout.tsx) - Protected layout template
  - [page-route.tsx](templates/page-route.tsx) - Basic page route template
  - [server-function.ts](templates/server-function.ts) - Server function template
  - [custom-hook.ts](templates/custom-hook.ts) - Custom query hook template

- **[checklists/](checklists/)** - Pre-PR validation
  - [tanstack-checklist.md](checklists/tanstack-checklist.md) - TanStack patterns checklist

## When to Apply This Skill

Use this skill when:
- Building TanStack Start applications
- Implementing routing with TanStack Router
- Managing server state with TanStack Query
- Creating server functions for data fetching
- Optimizing query performance with caching
- Implementing multi-tenant data access
- Setting up authentication flows with route protection
- Building data-heavy React applications

## Template Reference

These patterns are from Grey Haven's production template:
- **cvi-template**: TanStack Start + Router + Query + React 19

## Critical Reminders

1. **staleTime**: Default 60000ms (1 minute) for queries
2. **Query keys**: Specific to general (["user", userId], not [userId])
3. **Server functions**: Always include tenant_id parameter
4. **Multi-tenant**: Filter by tenant_id in all server functions
5. **Loaders**: Use for server-side data fetching before render
6. **Mutations**: Invalidate queries after successful mutation
7. **Prefetching**: Use for performance on hover/navigation
8. **Error handling**: Always handle error state in queries
9. **RLS**: Server functions use RLS-enabled database connection
10. **File-based routing**: Underscore prefix (_) for route groups/layouts