Skip to main content
affpapa.org
RU EN
skill CX Codex

safe-action-tanstack-query — Claude Code skill: setup

Connects next-safe-action mutations to TanStack Query with typed error handling, cache updates, and invalidation. Use it when React Query already handles your client data.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add next-safe-action/skills --skill safe-action-tanstack-query -a claude-code
Open on GitHub

What safe-action-tanstack-query does

This skill explains how mutationOptions() fits into useMutation. It maps the safe action result into TanStack Query’s mutation model: returned server or validation failures become ActionMutationError, while successful results arrive as mutation data. The guide also covers isActionMutationError, hasServerError, and hasValidationErrors.

It describes cache-based optimistic changes with onMutate, query invalidation through queryClient.invalidateQueries(), retry backoff, DevTools, and paused mutation persistence. The integration requires @next-safe-action/adapter-tanstack-query and @tanstack/react-query.

There is a firm boundary: wrapped actions must be stateless .action() functions that return errors instead of throwing them. stateAction, throwValidationErrors: true, and throwServerError: true do not fit this adapter. It handles mutations, not data fetching queries.

What it helps with

  • connect a safe action to useMutation
  • map server and validation failures to typed errors
  • invalidate the client query cache after a write
  • apply an optimistic cache update with onMutate
  • configure retries and paused mutation persistence

Example prompts for the agent

  • Connect createUser to useMutation with mutationOptions() and handle its returned data.
  • Show how to distinguish serverError from validationErrors with ActionMutationError and the type guards.
  • Add an optimistic cache update in onMutate, then invalidate the related queries with queryClient.invalidateQueries().

How to install safe-action-tanstack-query

1Skills CLI (Vercel)

npx skills add next-safe-action/skills --skill safe-action-tanstack-query -a claude-code

2Manually: put the files in place

~/.claude/skills/safe-action-tanstack-query/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/safe-action-tanstack-query/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about safe-action-tanstack-query

How do I install safe-action-tanstack-query in Claude Code?

Run npx skills add next-safe-action/skills --skill safe-action-tanstack-query -a claude-code, then check ~/.claude/skills/safe-action-tanstack-query/SKILL.md.

What does safe-action-tanstack-query do?

It documents an adapter for using next-safe-action with TanStack Query mutations. The skill covers result errors, typed guards, cache updates, and query invalidation.

Which actions can the adapter wrap?

Use stateless .action() functions that return errors in their result. Stateful actions and actions configured with throwValidationErrors: true or throwServerError: true are incompatible.

Similar skills

All skills for Frontend and UI →
frontend-design official anthropics This skill guides intentional visual design for new interfaces and redesigns. Use it when a generic generated UI is not enough. 1,025,790installs design-taste-frontend Leonxlnx This skill directs the design of public pages and work screens, then checks the result in a browser through screenshots. Use it when an interface feels generic or unfinished. CX Codex +1 678,700installs prototype Matt Pocock Creates throwaway prototypes for checking state logic or exploring UI before committing the decision to the main codebase. 986,201installs hyperframes heygen-com Instructs coding agents on creating, validating, and rendering HTML-based videos using the HyperFrames framework and CLI. CX Codex +1 1,200,000installs hyperframes-cli heygen-com Controls HyperFrames video workflows from the CLI: audits layouts and contrast, edits timeline clips, captures snapshots, and renders locally or in cloud runtimes. CX Codex +1 1,300,000installs webapp-testing official anthropics This skill tests local web apps with Playwright, helping agents debug UI behavior, capture screenshots, and inspect browser logs. 186,758installs

From the same set9

safe-action-middleware A skill that walks your agent through writing next-safe-action middleware: auth, authorization, logging, rate limits and context extension. CX Codex +1 1,200installs safe-action-validation-errors Guides coding assistants on handling input and manual validation errors in next-safe-action. Useful when writing server actions and UI error displays. CX Codex +1 1,200installs safe-action-advanced This skill covers advanced next-safe-action patterns for bound inputs, metadata, framework errors, inferred types, and server callbacks. CX Codex +1 1,200installs safe-action-hooks A skill that tells your agent which next-safe-action hook fits a form or optimistic UI, and how to wire it to the server action. CX Codex +1 1,200installs safe-action-client Guides agents in configuring next-safe-action clients and defining type-safe Next.js server actions with input schemas and structured error returns. CX Codex +1 1,200installs safe-action-forms This skill guides next-safe-action form integrations, from native HTML submission to React Hook Form, optimistic updates, and file uploads. CX Codex +1 1,200installs safe-action-testing Tells the agent how to write Vitest tests for next-safe-action actions and hooks: validation, middleware, server errors. CX Codex +1 1,100installs safe-action-better-auth This skill wires Better Auth into next-safe-action: the middleware fetches the session, rejects unauthenticated calls and hands you a typed context. CX Codex +1 477installs

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor