React Query Best Practices

A comprehensive compilation of React Query v4 best practices drawn from TkDodo's blog series, organized into 24 rules across categories like query keys, mutations, caching, and WebSocket integration. The skill covers critical patterns like query key factories, mutation invalidation strategies, and optimistic updates, plus it includes a detailed migration guide to v5 with all the breaking changes. Each rule follows a consistent format with wrong and right code examples. This is genuinely useful if you're past the basics and need to standardize patterns across a team or debug why your queries are refetching too often. The WebSocket integration rules alone are worth having on hand since that's rarely covered well in official docs.

skills.sh installs: 339
GitHub stars: 2
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add arraydude/agent-skills --skill react-query-best-practices --agent claude-code

Installs into .claude/skills of the current project.

Files

React Query Best Practices

Rules for @tanstack/react-query v4 and v5, checked against the library source (5.107.1 and 4.44.0), docs and changelog, and based on TkDodo's blog series. Each rule lives in rules/<id>.md with incorrect and correct code.

Pin the version first

Read the installed version from the lockfile entry for @tanstack/react-query (the package.json range can lie). Then:

Apply the rules whose versions frontmatter includes that major.
Skip a rule whose since is above the installed version.
Inside a rule, use the code block labelled for that version. Unlabelled code is valid for every version the rule lists.
Only the v3 package react-query present → these rules don't apply.

To move a repo to the latest v5 (and unlock the skipped rules), run the /react-query-migrate-v5 skill. It applies the migration- and upgrade- rules in order.