Skill

nextjs-tanstack-query

TanStack Query v5 integration with Next.js 16. Server-side prefetching, hydration, useQuery, useMutation, cache management.

From fuse-nextjs

Install

Run in your terminal

npx claudepluginhub fusengine/agents --plugin fuse-nextjs

Tool Access

This skill uses the workspace's default tool permissions.

Supporting Assets

View in Repository

references/hydration.md

references/query-patterns.md

Skill Content

Similar Skills

agent-harness-construction

Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.

ecc

140.3k

agent-payment-x402

Enables AI agents to execute x402 payments with per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents pay for APIs, services, or other agents.

ecc

140.3k

agent-eval

Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.

ecc

140.3k

Stats

Parent Repo Stars4

Parent Repo Forks0

Last CommitMar 26, 2026

Actions

View Source View Plugin View on GitHub View README

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

fuse-ai-pilot:explore-codebase - Analyze existing data fetching patterns

fuse-ai-pilot:research-expert - Verify latest TanStack Query v5 docs

mcp__context7__query-docs - Check TanStack Query + Next.js patterns

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

When to Use

Client-side data fetching with caching and revalidation

Server-side prefetching with hydration to client

Optimistic updates for mutations

Infinite scrolling and pagination

Real-time data synchronization

Why TanStack Query

Feature

Benefit

Server prefetching

Data ready on first render, no loading flash

Automatic caching

Deduplication, stale-while-revalidate

Mutations

Optimistic updates, rollback on error

DevTools

Visual cache inspection

TypeScript-first

Full type inference

Critical Rules

One QueryClient per request - Create in Server Component, share via context

Prefetch in Server Components - Use prefetchQuery for SSR data

HydrationBoundary required - Wrap client tree to transfer server cache

Query keys must be serializable - Arrays of strings/numbers only

staleTime on prefetched queries - Prevent immediate refetch on mount

Never use queryClient in Client Components directly - Use hooks

Best Practices

Prefetch on server - Avoid loading states for critical data

Set staleTime - Prevent unnecessary refetches after hydration

Collocate query keys - Define keys near their usage

Invalidate on mutation - Use invalidateQueries after writes

Error boundaries - Use throwOnError for critical queries

DevTools in dev only - Wrap in process.env.NODE_ENV check

Need

Reference

useQuery, useMutation

Server prefetching

QueryClient setup

Cache invalidation

TanStack Query for Next.js

TanStack Query v5 provides powerful server state management with Next.js 16 integration.

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

fuse-ai-pilot:explore-codebase - Analyze existing data fetching patterns
fuse-ai-pilot:research-expert - Verify latest TanStack Query v5 docs
mcp__context7__query-docs - Check TanStack Query + Next.js patterns

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

When to Use

Client-side data fetching with caching and revalidation
Server-side prefetching with hydration to client
Optimistic updates for mutations
Infinite scrolling and pagination
Real-time data synchronization

Why TanStack Query

Feature	Benefit
Server prefetching	Data ready on first render, no loading flash
Automatic caching	Deduplication, stale-while-revalidate
Mutations	Optimistic updates, rollback on error
DevTools	Visual cache inspection
TypeScript-first	Full type inference

Critical Rules

One QueryClient per request - Create in Server Component, share via context
Prefetch in Server Components - Use prefetchQuery for SSR data
HydrationBoundary required - Wrap client tree to transfer server cache
Query keys must be serializable - Arrays of strings/numbers only
staleTime on prefetched queries - Prevent immediate refetch on mount
Never use queryClient in Client Components directly - Use hooks

Installation

bun add @tanstack/react-query @tanstack/react-query-devtools

Best Practices

Prefetch on server - Avoid loading states for critical data
Set staleTime - Prevent unnecessary refetches after hydration
Collocate query keys - Define keys near their usage
Invalidate on mutation - Use invalidateQueries after writes
Error boundaries - Use throwOnError for critical queries
DevTools in dev only - Wrap in process.env.NODE_ENV check

Reference Guide

Need	Reference
useQuery, useMutation	query-patterns.md
Server prefetching	hydration.md
QueryClient setup	hydration.md
Cache invalidation	query-patterns.md