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?

The Anti-Pattern: Premature Adoption

1. Start new project
2. Immediately install all TanStack libraries
3. Force everything through TanStack patterns
4. End up with over-engineered code

• 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

1. Build with vanilla Next.js 16, React 19, Tailwind
2. Get the app working well
3. Run the TanStack analysis prompt
4. Adopt TanStack only where it clearly improves things
5. 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

• API calls that need caching
• Data that's fetched frequently
• Optimistic updates
• Background refetching
• Pagination with caching
• Infinite scroll

• Simple one-time fetches
• Static data
• Data that doesn't need synchronization

TanStack Table

• Complex data tables with sorting/filtering
• Tables with pagination
• Column resizing/reordering
• Row selection
• Expandable rows
• Server-side data tables

• Simple static tables
• Tables with < 20 rows
• No interactivity needed

TanStack Form

• Complex multi-step forms
• Forms with complex validation
• Forms with dynamic fields
• Forms with async validation
• Wizard-style workflows

• Simple contact forms
• Forms with 3-4 fields
• Basic validation needs

TanStack Router

• Large apps needing type-safe routing
• Complex nested routes
• Route-based code splitting
• Search params management

• Using Next.js App Router (already good)
• Simple navigation needs
• Few routes

TanStack Virtual

• Lists with 1000+ items
• Infinite scroll views
• Large data grids
• Chat message lists

• Lists with < 100 items
• Already using windowing elsewhere
• Performance is fine without it

Integration Workflow

Step 1: Get App Working

• fetch

  or axios for API calls
• Native form handling
• Simple HTML tables
• Next.js routing

Step 2: Run Analysis

Step 3: Evaluate Suggestions

• Does the complexity justify the benefit?
• Is the current solution actually problematic?
• Will this improve maintainability?

Step 4: Selective Adoption

• Use TanStack Query but not Table
• Use Table for one complex table, not all tables
• Mix vanilla and TanStack approaches

Step 5: Repeat

Best Models for This Task

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()),
});

• 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(),
});

• 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

1. Don't over-adopt — Some vanilla patterns are fine
2. Measure the benefit — Does it actually improve the code?
3. Consider team familiarity — TanStack has a learning curve
4. Check bundle size — Only import what you need
5. Read the docs — TanStack documentation is excellent