TanStack Integration — Strategic Library Adoption
Philosophy: Avoid "man with a hammer syndrome" (to whom everything appears as a nail). Start vanilla, then strategically adopt TanStack where it provides clear benefits.
Timing: Use this AFTER your app is already working pretty well in vanilla Next.js/React/Tailwind.
What is TanStack?
TanStack is a set of high-quality libraries for web applications:
Library Purpose TanStack Query Server state management, caching, synchronization TanStack Table Headless table/grid logic TanStack Form Form state management and validation TanStack Router Type-safe routing TanStack Virtual Virtualization for large lists TanStack Ranger Range/slider components The Anti-Pattern: Premature Adoption
Don't do this:
Start new project Immediately install all TanStack libraries Force everything through TanStack patterns End up with over-engineered code
Why it's bad:
Not every feature needs TanStack Adds complexity where simple solutions work Makes code harder to understand for no benefit "Man with a hammer" sees every problem as a nail The Correct Pattern: Strategic Adoption
Do this instead:
Build with vanilla Next.js 16, React 19, Tailwind Get the app working well Run the TanStack analysis prompt Adopt TanStack only where it clearly improves things Repeat several rounds THE EXACT PROMPT — TanStack Analysis Ok, I want you to look through the ENTIRE project and look for areas where, if we leveraged one of the many TanStack libraries (e.g., query, table, forms, etc), we could make part of the code much better, simpler, more performant, more maintainable, elegant, shorter, more reliable, etc. Use ultrathink
When to Use Each TanStack Library TanStack Query
Good candidates:
API calls that need caching Data that's fetched frequently Optimistic updates Background refetching Pagination with caching Infinite scroll
Skip if:
Simple one-time fetches Static data Data that doesn't need synchronization TanStack Table
Good candidates:
Complex data tables with sorting/filtering Tables with pagination Column resizing/reordering Row selection Expandable rows Server-side data tables
Skip if:
Simple static tables Tables with < 20 rows No interactivity needed TanStack Form
Good candidates:
Complex multi-step forms Forms with complex validation Forms with dynamic fields Forms with async validation Wizard-style workflows
Skip if:
Simple contact forms Forms with 3-4 fields Basic validation needs TanStack Router
Good candidates:
Large apps needing type-safe routing Complex nested routes Route-based code splitting Search params management
Skip if:
Using Next.js App Router (already good) Simple navigation needs Few routes TanStack Virtual
Good candidates:
Lists with 1000+ items Infinite scroll views Large data grids Chat message lists
Skip if:
Lists with < 100 items Already using windowing elsewhere Performance is fine without it Integration Workflow Step 1: Get App Working
Build your app with vanilla patterns first:
fetch or axios for API calls Native form handling Simple HTML tables Next.js routing Step 2: Run Analysis
Use the TanStack analysis prompt with Claude Code + Opus 4.5 or Codex + GPT 5.2 (High reasoning effort).
Step 3: Evaluate Suggestions
The model will identify opportunities. For each:
Does the complexity justify the benefit? Is the current solution actually problematic? Will this improve maintainability? Step 4: Selective Adoption
Only adopt where there's clear benefit. It's fine to:
Use TanStack Query but not Table Use Table for one complex table, not all tables Mix vanilla and TanStack approaches Step 5: Repeat
Run the analysis again after changes. New opportunities may emerge.
Best Models for This Task Model Configuration Claude Code + Opus 4.5 Use ultrathink Codex + GPT 5.2 High or Extra-High reasoning effort Example Improvements Before: Manual Data Fetching // Vanilla approach const [data, setData] = useState(null); const [loading, setLoading] = useState(true); const [error, setError] = useState(null);
useEffect(() => { fetch('/api/users') .then(res => res.json()) .then(setData) .catch(setError) .finally(() => setLoading(false)); }, []);
After: TanStack Query // TanStack Query approach const { data, isLoading, error } = useQuery({ queryKey: ['users'], queryFn: () => fetch('/api/users').then(res => res.json()), });
Benefits:
Built-in caching Automatic refetching Request deduplication DevTools support Before: Complex Table Logic // Vanilla approach with manual sorting, filtering, pagination // ... 200+ lines of state management
After: TanStack Table // TanStack Table handles sorting, filtering, pagination const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel(), getSortedRowModel: getSortedRowModel(), getFilteredRowModel: getFilteredRowModel(), getPaginationRowModel: getPaginationRowModel(), });
Benefits:
Headless (you control the UI) All table logic handled Consistent behavior Much less code Creating Beads for TanStack Work bd create "Evaluate TanStack Query opportunities" -t enhancement -p 3 bd create "Migrate user data fetching to TanStack Query" -t enhancement -p 2 bd create "Implement data table with TanStack Table" -t feature -p 2 bd create "Add TanStack Virtual to chat message list" -t performance -p 2
Complete Prompt Reference TanStack Analysis Ok, I want you to look through the ENTIRE project and look for areas where, if we leveraged one of the many TanStack libraries (e.g., query, table, forms, etc), we could make part of the code much better, simpler, more performant, more maintainable, elegant, shorter, more reliable, etc. Use ultrathink
Focused Query Analysis Look through the project for data fetching patterns that would benefit from TanStack Query. Consider caching needs, refetching patterns, and optimistic updates. Identify the top 3 opportunities. Use ultrathink.
Focused Table Analysis Look through the project for table/grid components that would benefit from TanStack Table. Consider sorting, filtering, pagination, and column management needs. Identify candidates. Use ultrathink.
Tips Don't over-adopt — Some vanilla patterns are fine Measure the benefit — Does it actually improve the code? Consider team familiarity — TanStack has a learning curve Check bundle size — Only import what you need Read the docs — TanStack documentation is excellent