{"id":"ebb0d4ad-1d71-44b2-97d8-580a31795a53","shortId":"Svt5BZ","kind":"skill","title":"tanstack","tagline":"Use when editing TanStack code, @tanstack imports, useQuery, createRouter, React Query, TanStack Router, Table, Form, Store, file-based routing, data fetching, or SPA state management.","description":"# TanStack Ecosystem\n\nThe TanStack ecosystem provides standard libraries for modern React/TypeScript applications, emphasizing type safety, performance, and developer experience.\n\n## Quick Reference\n\n### useQuery Pattern (with Query Options Factory)\n\n```tsx\nimport { queryOptions, useQuery } from '@tanstack/react-query'\n\n// Define query options as a factory -- reusable across components and loaders\nexport const usersQueryOptions = (filters?: UserFilters) =>\n queryOptions({\n queryKey: ['users', filters],\n queryFn: () => api.getUsers(filters),\n staleTime: 5 * 60 * 1000, // 5 minutes\n })\n\nfunction UsersPage() {\n const { data, isLoading, error } = useQuery(usersQueryOptions())\n\n if (isLoading) return \n if (error) return \n\n return \n}\n```\n\n### Mutations with Cache Invalidation\n\n```tsx\nexport function useCreateUser() {\n const queryClient = useQueryClient()\n\n return useMutation({\n mutationFn: (data: UserCreate) => api.createUser(data),\n onSuccess: () => {\n queryClient.invalidateQueries({ queryKey: ['users'] })\n },\n })\n}\n```\n\n### File-Based Routing (TanStack Router)\n\n```text\nsrc/routes/\n├── __root.tsx # Root layout\n├── index.tsx # / route\n├── _layout.tsx # Layout wrapper (no URL segment)\n├── users/\n│ ├── index.tsx # /users\n│ ├── $userId.tsx # /users/:userId\n│ └── $userId.edit.tsx # /users/:userId/edit\n```\n\n### Route with Loader & Query Pre-fetching\n\n```tsx\nimport { createFileRoute } from '@tanstack/react-router'\nimport { queryClient } from '@/lib/query-client'\n\nexport const Route = createFileRoute('/users')({\n loader: () => queryClient.ensureQueryData(usersQueryOptions()),\n component: UsersPage,\n})\n\n// Route parameters\nexport const Route = createFileRoute('/users/$userId')({\n loader: ({ params }) =>\n queryClient.ensureQueryData(userQueryOptions(params.userId)),\n component: UserDetailPage,\n})\n```\n\n### Search Parameters (Zod Validation)\n\n```tsx\nimport { z } from 'zod'\n\nconst searchSchema = z.object({\n page: z.number().default(1),\n sort: z.enum(['name', 'date']).default('name'),\n})\n\nexport const Route = createFileRoute('/users')({\n validateSearch: searchSchema,\n component: UsersPage,\n})\n```\n\n### TanStack Table Basics\n\n```tsx\nimport { useReactTable, getCoreRowModel, flexRender, ColumnDef } from '@tanstack/react-table'\n\nconst columns: ColumnDef[] = [\n { accessorKey: 'name', header: 'Name' },\n { accessorKey: 'email', header: 'Email' },\n {\n accessorKey: 'createdAt',\n header: 'Joined',\n cell: (info) => new Date(info.getValue()).toLocaleDateString(),\n },\n]\n\nfunction UsersTable({ users }: { users: User[] }) {\n const table = useReactTable({\n data: users,\n columns,\n getCoreRowModel: getCoreRowModel(),\n })\n // render with flexRender -- see references/table.md\n}\n```\n\n\n\n## Workflow\n\n### Step 1: Identify the Library\n\n| Need | Library | Key Import |\n| --- | --- | --- |\n| Data fetching & caching | TanStack Query | `@tanstack/react-query` |\n| Client-side routing | TanStack Router | `@tanstack/react-router` |\n| Table / data grid | TanStack Table | `@tanstack/react-table` |\n| Form state & validation | TanStack Form | `@tanstack/react-form` |\n| Lightweight state | TanStack Store | `@tanstack/store` |\n\n### Step 2: Implement\n\n1. **Query**: Define query options factories with `queryOptions()` -- always set `staleTime`\n2. **Router**: Use file-based routing with `createFileRoute` -- pre-fetch with `loader`\n3. **Table**: Define `ColumnDef[]` typed to your data -- use `getCoreRowModel()` as base\n4. **Form**: Use `useForm()` with Zod adapter for validation\n\n### Step 3: Integrate Router + Query\n\n1. Create query options factories in a shared location (e.g., `@/lib/queries/`)\n2. Use `ensureQueryData` in route loaders for data pre-fetching\n3. Use the same query options in components with `useQuery` for cache hits\n4. Prefetch on hover with `queryClient.prefetchQuery()` for navigation links\n\n### Step 4: Validate\n\nRun through the validation checkpoint below before considering the work complete.\n\n\n\n\n\n## Guardrails\n\n- **Always set `staleTime`** on queries -- the default (0) causes unnecessary refetches on every mount\n- **Always use `queryKey` arrays** -- include all variables the query depends on: `['users', filters]`\n- **Always use `queryOptions()` factory** -- makes query keys reusable across components and loaders\n- **Always handle loading and error states** -- `isLoading`, `error` from `useQuery` must be checked\n- **Prefetch on hover** for navigation links -- use `queryClient.prefetchQuery()` in `onMouseEnter`\n- **Never use inline queryFn without queryKey** -- keys must be stable and serializable\n- **Never mutate query data directly** -- use `queryClient.setQueryData()` for optimistic updates\n- **TanStack Router is NOT react-router** -- do not mix `` components or hooks between them\n\n\n\n\n\n### Validation Checkpoint\n\nBefore delivering TanStack code, verify:\n\n- [ ] All `useQuery` calls have `staleTime` set (via `queryOptions` factory or directly)\n- [ ] Query keys include all dependent variables (no stale closures)\n- [ ] Loading and error states are handled in every component that fetches data\n- [ ] Route loaders use `ensureQueryData` (not `fetchQuery`) to leverage cache\n- [ ] Mutations invalidate related query keys on success\n- [ ] Table column definitions are typed with `ColumnDef[]`\n\n\n\n\n\n## Example\n\n**Task:** \"Create a users list page with TanStack Router + Query, including search, pagination, and prefetch on hover.\"\n\n```tsx\n// --- lib/queries/users.ts ---\nimport { queryOptions } from '@tanstack/react-query'\nimport { api } from '@/lib/api'\n\ninterface UserFilters {\n search?: string\n page?: number\n}\n\nexport const usersQueryOptions = (filters: UserFilters = {}) =>\n queryOptions({\n queryKey: ['users', filters],\n queryFn: () => api.getUsers(filters),\n staleTime: 5 * 60 * 1000,\n })\n\nexport const userQueryOptions = (userId: string) =>\n queryOptions({\n queryKey: ['users', userId],\n queryFn: () => api.getUser(userId),\n staleTime: 5 * 60 * 1000,\n })\n\n\n// --- routes/users/index.tsx ---\nimport { createFileRoute } from '@tanstack/react-router'\nimport { z } from 'zod'\nimport { usersQueryOptions } from '@/lib/queries/users'\nimport { queryClient } from '@/lib/query-client'\n\nconst searchSchema = z.object({\n search: z.string().optional(),\n page: z.number().default(1),\n})\n\nexport const Route = createFileRoute('/users/')({\n validateSearch: searchSchema,\n loader: ({ search }) =>\n queryClient.ensureQueryData(usersQueryOptions(search)),\n component: UsersPage,\n})\n\nfunction UsersPage() {\n const { search, page } = Route.useSearch()\n const navigate = Route.useNavigate()\n const { data, isLoading, error } = useQuery(\n usersQueryOptions({ search, page }),\n )\n\n if (isLoading) return \n if (error) return \n\n return (\n \n
navigate({ search: { search: value, page: 1 } })}\n />\n \n navigate({ search: { search, page: p } })}\n />\n