TanStack

Status: Active
Last Updated: 2026-08-26
Category: Frontend / React
Prerequisites: routing-patterns.md, component-library-notes.md
Tags: tanstack, query, router, table, devtools, react

Summary

The TanStack ecosystem (Query, Router, Table, Devtools) emphasizes explicit caching, loaders/actions, and dev tooling that fits agentic dashboards tied to GitOps data. Use precise query keys, derive tables from the Query cache, and ship devtools in dev only.

Context / Why This Matters

Without a single source of truth for client state, agents and humans duplicate fetches, race on mutations, and break expectations. TanStack's contract (Query cache as truth, Router loaders for prefetch, Table as derived view) maps cleanly onto KB-driven dashboards.

Implementation / Core Content

Query Fundamentals

• QueryClient defaults: configure retry, suspense, staleTime as the foundation for agent dashboards.
• Precise query keys: use nested arrays so agents can target subset invalidations without re-fetching entire graphs.
• Devtools: ship in dev for cache inspection; in prod, gate behind a flag for remote debugging.

Router + Table Patterns

• TanStack Router supports loaders / actions that map to GitOps tickets, enabling prefetching and optimistic updates.
• Tables derive their data from the Query cache, so a single source of truth avoids duplication.
• TanStack Table plugins: sorting / filtering / column pinning / aggregation for telemetry dashboards.

Devtools & Observability

• useHydrate and devtools help debug caching mismatches.
• Bundle devtools only in dev builds; enable remote debugging for agents in production (gated).
• TanStack Table plugin system supports dynamic network maps in the KB browser.

Practical Examples

// TanStack Query: precise key for partial invalidation
const queryClient = new QueryClient();
queryClient.setQueryData(['repo', 'kb', 'research', 'README'], data);
queryClient.invalidateQueries({ queryKey: ['repo', 'kb'] }); // subset

// TanStack Router: loader maps to a KB article id
export const Route = createFileRoute('/kb/$articleId')({
  loader: ({ params, context }) =>
    context.queryClient.ensureQueryData({
      queryKey: ['kb', params.articleId],
      queryFn: () => fetchArticle(params.articleId),
    }),
  component: ArticleView,
});

Common Pitfalls & Troubleshooting

Pitfall	Fix
Query keys are too coarse	Use nested arrays; invalidate only what changed
Stale data after mutation	Call invalidateQueries with the precise key
Devtools shipped to prod	Gate behind a build-time flag
Tables duplicating data	Derive columns from the Query cache; never fetch inside table components
useHydrate missing on SSR	Hydrate from server-provided initial data on the client

Next Steps / Ops Actions

1. Capture Query key conventions in frontend/tanstack.md.
2. Document the Router loader/action pattern for operations dashboards tied to Forgejo Issues.
3. Keep the Devtools workflow documented so agents can verify React state before merging.

Sources & Related Articles

• TanStack Query overview.
• Query key hygiene + caching recommendations.
• TanStack Router guide (loaders, actions).
• TanStack Table introduction.
• TanStack Devtools documentation.
• Related KB: routing-patterns.md, component-library-notes.md

Change Log

2026-08-26

• Expanded from 2.3KB research log to production-quality article with full format, examples, pitfalls, and operational links.