Skill: openlark/tanstack-libraries (version 1.0.0)

--- name: tanstack-libraries description: Use when users ask about TanStack libraries, TanStack Start/Router/Query/Table/Form/Virtual/Store/DB/Pacer/Config/DevTools/CLI/Intent/Hotkeys/AI usage, package names, framework adapters, maturity status, documentation URLs, installation methods, core APIs, code examples. --- # TanStack Libraries Headless, type-safe, framework-agnostic collection of web tooling libraries. > **Need code examples or detailed features?** Read by category: > - [Data & State](references/data-state.md) — Start / Router / Query / DB / Store / AI > - [UI & UX](references/ui-ux.md) — Table / Form / Hotkeys > - [Performance](references/performance.md) — Virtual / Pacer > - [Tooling](references/tooling.md) — Devtools / Config / CLI / Intent ## Library Overview ### Stable | Library | Core Package | Framework Adapters | Purpose | |---|---|---|---| | **Query** | `@tanstack/query-core` | react / vue / solid / svelte / angular / lit | Async state management, data fetching/caching/synchronization | | **Router** | `@tanstack/router-core` | react / solid | Type-safe routing, Search Params, Loader+SWR caching | | **Table** | `@tanstack/table-core` | react / vue / solid / svelte / angular / qwik / lit | Headless tables: sorting/filtering/pagination/grouping/aggregation | | **Virtual** | `@tanstack/virtual-core` | react / vue / solid / svelte / angular / lit | Virtual scrolling (vertical/horizontal/grid) | | **Config** | `@tanstack/config` | — | JS/TS package publishing toolchain (pnpm only) | ### RC | Library | Core Package | Framework Adapters | Purpose | |---|---|---|---| | **Start** | `@tanstack/react-start` `@tanstack/solid-start` | react / solid | Full-stack framework: SSR/Streaming/Server Functions/RSC, built on Router+Vite | ### New | Library | Core Package | Framework Adapters | Purpose | |---|---|---|---| | **Form** | `@tanstack/form-core` | react / vue / angular / solid / lit / preact | Headless form state management, nested fields, async validation | ### Beta | Library | Package | Framework Adapters | Purpose | |---|---|---|---| | **DB** | `@tanstack/db` | react (runtime framework-agnostic) | Reactive client-side storage: Collections + Live Queries + Optimistic mutations | | **Pacer** | `@tanstack/pacer` `@tanstack/pacer-lite` | react / solid | Debounce/throttle/rate-limit/queue/batching | | **Store** | `@tanstack/store` | react / vue / angular / solid / svelte | Immutable reactive data store (internal TanStack core dependency) | ### Alpha | Library | Package | Framework Adapters | Purpose | |---|---|---|---| | **AI** | `@tanstack/ai` `@tanstack/ai-client` `@tanstack/ai-react` `@tanstack/ai-solid` | react / solid + server | AI SDK: multi-Provider, tool calling, streaming, speech | | **Hotkeys** | `@tanstack/hotkeys` | react / preact / solid / angular / vue / lit | Type-safe keyboard shortcuts, sequences, recording | | **Devtools** | `@tanstack/devtools` and 7 other packages | react / vue / solid / preact | Unified DevTools panel, plugin system, source jumping | | **CLI** | `@tanstack/cli` | — | Scaffold Start projects, Add-ons, MCP Server | | **Intent** | `@tanstack/intent` | — | Publish Agent Skills via npm, auto-discovery, staleness detection | ## Core Design Principles 1. **Framework-agnostic** — Core libraries (`*-core`) → Framework adapters 2. **Headless** — Logic completely decoupled from UI, 100% control over markup and styling 3. **Type-safe** — First-class TypeScript support 4. **Lightweight** — Typically 10-15KB, tree-shakeable, zero dependencies 5. **No vendor lock-in** — Fully open source, self-funded

path: references/data-state.md
content: # Data & State

> Start / Router / Query / DB / Store / AI

---

## Query

**Installation:** `npm i @tanstack/react-query` (adapters: react/vue/solid/svelte/angular/lit)

```ts
// Provider
const queryClient = new QueryClient()
// <QueryClientProvider client={queryClient}>

// Queries
const { data, isPending, error } = useQuery({ queryKey: ['todos'], queryFn: () => fetch('/api/todos').then(r => r.json()) })

// Mutations
const mutation = useMutation({
  mutationFn: (todo) => fetch('/api/todos', { method: 'POST', body: JSON.stringify(todo) }),
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
})

// Status: status(pending/error/success) + fetchStatus(fetching/paused/idle)
// Invalidation: queryClient.invalidateQueries({ queryKey: ['todos'] })
// Prefetching: queryClient.prefetchQuery({ queryKey, queryFn, staleTime })
// Parallel: useQuery + useQuery / useQueries({ queries: [...] })
// Pagination: placeholderData: keepPreviousData
// Infinite scrolling: useInfiniteQuery({ getNextPageParam })
// Suspense: useSuspenseQuery({ queryKey, queryFn })
// Network mode: online(default) / always / offlineFirst
// staleTime(cache freshness duration) vs gcTime(garbage collection time)
```

**v5 changes:** All hooks unified to single object signature `useQuery({ queryKey, queryFn })`

**Optimistic updates:**
```ts
onMutate: async (vars) => {
  await queryClient.cancelQueries({ queryKey })
  const prev = queryClient.getQueryData(queryKey)
  queryClient.setQueryData(queryKey, old => [...old, vars])
  return { prev }  // → onMutateResult
},
onError: (err, vars, onMutateResult) => queryClient.setQueryData(queryKey, onMutateResult.prev),
onSettled: () => queryClient.invalidateQueries({ queryKey }),
```

**Mutations lifecycle:** `onMutate → mutationFn → onSuccess/onError → onSettled`

**ESLint:** `npm i -D @tanstack/eslint-plugin-query` (detects missing useQuery dependencies, conservative staleTime, etc.)

---

## Router

**Installation:** `npm i @tanstack/react-router` (adapters: react/solid)

```ts
// Type registration
declare module '@tanstack/react-router' { interface Register { router: typeof router } }

// File-based routing (src/routes/)
// posts.$postId.tsx → export const Route = createFileRoute('/posts/$postId')({
//   loader: ({ params }) => fetchPost(params.postId),
//   component: () => { const { postId } = Route.useParams(); return <div>{postId}</div> }
// })

// Code-based routing
const rootRoute = createRootRoute()
const indexRoute = createRoute({ getParentRoute: () => rootRoute, path: '/', component: Index })
const router = createRouter({ routeTree: rootRoute.addChildren([indexRoute]) })
```

**Core features:**
- 100% type inference (path params/Search/navigation)
- Search Params JSON auto-parsing + Schema validation
- Loader + SWR caching (can integrate with Query)
- Code splitting: `autoCodeSplitting: true` / `.lazy.tsx` / Virtual Routes
- Navigation blocking: `useBlocker({ shouldBlockFn })`

**Data loading lifecycle:** Route Matching → `beforeLoad` (serial) → `loader` (parallel)

**Query integration:**
```ts
const opts = queryOptions({ queryKey: ['posts'], queryFn: fetchPosts })
export const Route = createFileRoute('/posts')({
  loader: () => queryClient.ensureQueryData(opts),
  component: () => { const { data } = useSuspenseQuery(opts); return ... }
})
```

---

## Start (RC)

Full-stack framework: SSR/Streaming/Server Functions/RSC, built on Router+Vite.
- `@tanstack/react-start` / `@tanstack/solid-start`

---

## DB (Beta)

Based on TypeScript differential dataflow (d2ts):
```ts
const todos = createCollection(queryCollectionOptions({ queryKey: ['todos'], queryFn: fetchTodos, getKey: (item) => item.id }))
const { data } = useLiveQuery((q) => q.from({ todo: todos }).where(({ todo }) => !todo.completed))
todos.update(id, (draft) => { draft.completed = true })  // Optimistic mutation
```

Sync modes: eager (<10k full) / on-demand (component query) / progressive
Collection types: Query / Electric / TrailBase / RxDB / PowerSync / LocalStorage
Schema: Compatible with Standard Schema (Zod/Valibot/ArkType/Effect)

---

## Store (Alpha)

```ts
import { Store } from '@tanstack/store'
const store = new Store({ count: 0 })
store.setState((s) => ({ count: s.count + 1 }))
```

Internal TanStack core dependency, drives Form/Router/Pacer. Adapters: react/vue/angular/solid/svelte.

---

## AI (Alpha)

Unified interface for multiple Providers (openrouter/openai/anthropic/gemini/ollama/groq/grok/fal).

```bash
npm i @tanstack/ai @tanstack/ai-react @tanstack/ai-openai
```

```ts
import { chat, toolDefinition } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'

const getProducts = toolDefinition({
  name: 'getProducts',
  inputSchema: z.object({ query: z.string() }),
}).server(async ({ query }) => await db.search(query))

chat({ adapter: openaiText('gpt-5.2'), messages: [...], tools: [getProducts] })
```

Features: Isomorphic tools (.server/.client), streaming + Thinking tokens, middleware, Code Mode (Sandbox TS), real-time speech

path: references/performance.md
content: # Performance

> Virtual / Pacer

---

## Virtual

Virtual scrolling (vertical/horizontal/grid).

```bash
npm i @tanstack/react-virtual  # adapters: react/vue/solid/svelte/angular/lit
```

```ts
import { useVirtualizer } from '@tanstack/react-virtual'

const virtualizer = useVirtualizer({
  count: 10000,
  getScrollElement: () => scrollRef.current,
  estimateSize: () => 35,  // or getItemSize for dynamic height
  overscan: 5,             // Number of items to render outside the viewport
})

// virtualizer.getVirtualItems() → { index, size, start }[]
// virtualizer.getTotalSize() — Total height
// Manual setting of scroll container height and item positioning required
```

**Windowed vs Non-windowed:** Virtual windowed (renders only visible items) handles millions of rows at O(rows_visible) complexity. TanStack Table supports non-windowed out of the box (O(rows_total)).

**Use cases:** Flat lists, grids, fixed/variable sizing, sticky indices, smooth scrolling, SSR compatibility.

---

## Pacer (Beta)

Debounce/throttle/rate-limit/queue/batching.

```bash
npm i @tanstack/react-pacer  # adapters: react/solid
npm i @tanstack/pacer-lite   # Framework-agnostic version
```

```ts
import { useDebouncer, useThrottler, useQueuer } from '@tanstack/react-pacer'

const debounced = useDebouncer(search, { wait: 300 })
const throttled = useThrottler(scroll, { wait: 100, leading: true })
const queued = useQueuer(save, { concurrency: 3 })
```

Function-based versions: `debounce(fn, { wait })`, `throttle(fn, { wait, leading })`, `queue(fn, { concurrency })`, `batch(fn, { wait, maxSize })`

path: references/tooling.md
content: # Tooling

> Devtools / Config / CLI / Intent

---

## Devtools (Alpha)

Unified DevTools panel (Solid.js), supports plugin system.

```bash
npm i -D @tanstack/react-devtools @tanstack/devtools-vite
```

```tsx
import { TanStackDevtools } from '@tanstack/react-devtools'
<TanStackDevtools plugins={[
  { name: 'Query', render: <ReactQueryDevtoolsPanel /> },
  { name: 'Router', render: <TanStackRouterDevtoolsPanel /> },
]} />
```

Packages: `@tanstack/devtools` (core Shell/plugin system) | framework adapters (react/vue/solid/preact-devtools) | `devtools-vite` (source inspection/production stripping) | `devtools-event-client/bus` (WebSocket/SSE)

Features: Plugin system and marketplace, source jumping, console piping, Picture-in-Picture (PiP)

---

## Config

JS/TS package publishing toolchain (pnpm only).

```bash
npm i -D @tanstack/config
pnpm exec tsc-build  # Typed build system, replaces tsc -b
```

Built-in: Build (Eslint/Prettier/esbuild/TypeScript), Testing (Vitest), Publishing (git tag + changelog + GitHub release)

---

## CLI (Alpha)

```bash
npm i -g @tanstack/cli
npx @tanstack/cli create   # Scaffold Start projects
```

Features: Add-ons extension system, MCP Server integration

---

## Intent (Alpha)

```bash
npm i -D @tanstack/intent
```

Publish Agent Skills via npm packages, with auto-discovery and staleness detection. `.intent/` directory manifest → `npx @tanstack/intent doctor` for diagnostics.

path: references/ui-ux.md
content: # UI & UX

> Table / Form / Hotkeys

---

## Table

Headless — provides logic/state/API, no markup or styling.

```bash
npm i @tanstack/react-table  # adapters: react/vue/solid/svelte/angular/qwik/lit
```

```ts
const table = useReactTable({
  data, columns,
  getCoreRowModel: getCoreRowModel(),
  getSortedRowModel: getSortedRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
})

// Rendering: table.getHeaderGroups() → <thead>, table.getRowModel().rows → <tbody>
// flexRender(header.column.columnDef.header, header.getContext())
```

### Column Definition

```ts
const columnHelper = createColumnHelper<Person>()

const columns = [
  columnHelper.display({ id: 'actions', cell: props => <RowActions row={props.row} /> }),  // No data model
  columnHelper.group({ header: 'Name', columns: [
    columnHelper.accessor('firstName', { header: 'First Name' }),         // Object key
    columnHelper.accessor(row => row.lastName, { id: 'lastName' }),       // Function (requires id)
  ]}),
  columnHelper.accessor('age', { cell: props => <span>{props.getValue()}</span> }),
]
```

Three column types: Accessor (has data model) | Display (pure display) | Group (grouping)

### Features

| Feature | Configuration |
|---------|---------------|
| Sorting | `getSortedRowModel: getSortedRowModel()`, `state: { sorting }` |
| Pagination | `getPaginationRowModel: getPaginationRowModel()` |
| Filtering | `getFilteredRowModel: getFilteredRowModel()`, `state: { columnFilters }` |
| Row Selection | `enableRowSelection: true`, `state: { rowSelection }`, `getRowId: row => row.uuid` |
| Aggregation | `aggregationFn: 'sum'`, `getAggregatedRowModel` |

Server-side mode: `manualSorting/Filtering/Pagination: true` + `rowCount: totalRows`

### Styling

- No built-in styles — 50+ community styling solutions available (shadcn/ui, Mantine, Chakra, Ant Design, etc.)
- TanStack Start projects have built-in `@tanstack/react-table` integration

---

## Form

Headless form state management, supports nested fields and async validation.

```bash
npm i @tanstack/react-form  # adapters: react/vue/angular/solid/lit/preact
```

```tsx
import { useForm } from '@tanstack/react-form'

const form = useForm({
  defaultValues: { name: '', age: 0 },
  onSubmit: async ({ value }) => { await api.submit(value) },
})

<form.Field name="name" validators={{ onChange: ({ value }) => !value ? 'Required' : undefined }}>
  {(field) => <input value={field.state.value} onChange={e => field.handleChange(e.target.value)} />}
</form.Field>
```

- Validation: `onChange`/`onBlur`/`onSubmit` three levels, supports Zod/Yup/Superstruct adapters
- Array fields: `form.useField({ name: 'items' })` + `.push/.remove/.move/.swap`
- Plugin system: `@tanstack/zod-form-adapter`, etc.

---

## Hotkeys (Alpha)

Type-safe keyboard shortcuts. `npm i @tanstack/hotkeys`

```ts
import { useHotkeys } from '@tanstack/react-hotkeys'
useHotkeys({
  'meta+k': () => openSearch(),
  'ctrl+s': () => save(),
  'shift+?': () => showPalette(),
  'a b c': () => konami(),  // Sequence
})
```
Supports recording/replay, platform awareness (Ctrl vs ⌘).

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)