Skip to content
Skills Library
Programming · Building & coding

nextjs-tanstack-query

/nextjs-tanstack-query

Use when implementing client-side data fetching, server prefetching with hydration, or optimistic mutations in Next.js 16 with TanStack Query.

Repository
agents ↗
Licence
MIT
Last repository change
12.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when implementing client-side data fetching, server prefetching with hydration, or optimistic mutations in Next.js 16 with TanStack Query.

Original author description

Use when implementing client-side data fetching, server prefetching with hydration, or optimistic mutations in Next.js 16 with TanStack Query.

How it works

  1. Agent Workflow (MANDATORY)
  2. Overview
  3. Critical Rules
  4. Installation
  5. Best Practices
  6. Reference Guide
Original SKILL.md headings · 84 lines, 437 words
SKILL.md preview
---
name: nextjs-tanstack-query
description: Use when implementing client-side data fetching, server prefetching with hydration, or optimistic mutations in Next.js 16 with TanStack Query.
versions:
  tanstack-query: 5
  nextjs: 16
  react: 19
user-invocable: true
references: references/query-patterns.md, references/hydration.md
related-skills: nextjs-16, nextjs-server-components, react-19
---

<objective>
Implements TanStack Query v5 server-state management in Next.js 16: creating one `QueryClient` per request in a Server Component and sharing it via context, `prefetchQuery` for SSR data with `HydrationBoundary` to transfer the server cache to the client, and optimistic mutations with rollback on error.

Covers serializable query keys, `staleTime` tuning on prefetched queries to avoid immediate refetch, cache invalidation with `invalidateQueries` after writes, infinite scrolling/pagination, and DevTools setup gated to development only. Does not cover the Server Component boundary itself (nextjs-server-components) or core Next.js caching primitives like `use cache` (nextjs-16) — this skill is specifically about TanStack Query's client-side cache layer.
</objective>

# TanStack Query for Next.js

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

## Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:

1. **fuse-ai-pilot:explore-codebase** - Analyze existing data fetching patterns
2. **fuse-ai-pilot:research-expert** - Verify latest TanStack Query v5 docs
3. **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

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

---

## Installation

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

---

## Best Practices

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

---

## Reference Guide

| Need | Reference |
|------|-----------|
| useQuery, useMutation | [query-patterns.md](references/query-patterns.md) |
| Server prefetching | [hydration.md](references/hydration.md) |
| QueryClient setup | [hydration.md](references/hydration.md) |
| Cache invalidation | [query-patterns.md](references/query-patterns.md) |
Files in this package (3)
  • SKILL.md 4 KB
  • references/hydration.md 3 KB
  • references/query-patterns.md 3 KB

Versions

The database has no other skills named nextjs-tanstack-query.

Database snapshot: 13.11.2026 · package version 2317760e4ceb (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100tanstack-query-expert
    TanStack Query (React Query) expertise: data fetching, stale time, mutations, optimistic updates, Next.js SSR. Use for async state management.
  • 100tanstack-query
    TanStack Query for data fetching. Covers queries, mutations, and caching. Use for server state management in React. USE WHEN: user mentions "tanstack query", "react query", "data fetching", "API calls", asks about "cache management", "mutations", "infinite scroll", "optimistic…
  • 91tanstack-query
    TanStack Query v5 (React Query) server state management. Use for data fetching, caching, mutations, or encountering v4 migration, stale data, invalidation errors.
  • 95tanstack-query-best-practices
    TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. Activate when building data-driven React applications with server state.
  • 100tanstack-query
    TanStack Query v5 performance optimization for data fetching, caching, mutations, and query patterns. This skill should be used when using useQuery, useMutation, queryClient, prefetch patterns, or TanStack Query caching. This skill does NOT cover generating query hooks from…
  • 90TanStack Query
    Expert guidance for TanStack Query (React Query) including queries, mutations, caching, invalidation, optimistic updates, pagination, and infinite queries. Use this when managing server state in React applications.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.