safe-action-tanstack-query

Bridge Next Safe Action results with TanStack Query mutations.

1|Updated Feb 6, 2026

Search Tags:#error-handling #mutation #tanstack-query #server-actions #optimistic-updates #cache-invalidation

Ready to run

npx skills add https://github.com/gepetojj/umo --skill safe-action-tanstack-query

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: safe-action-tanstack-query
Source: https://github.com/gepetojj/umo/tree/main/.agents/skills/safe-action-tanstack-query
Command: npx skills add https://github.com/gepetojj/umo --skill safe-action-tanstack-query

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Bridges Next Safe Action results with TanStack Query mutations to ensure consistent error modeling and cache integration across client-server flows.

Core Features & Use Cases

Bridges action outcomes from Next Safe Action to TanStack Query's mutation flow, enabling unified error handling, navigation safety, and cache invalidation.
Exposes mutationOptions() that translate non-throwing action results into UseMutation-compatible data envelopes, with type guards for server and validation errors.
Supports optimistic updates and robust error recovery via onMutate, onError, and onSettled integration in client components.
Real-world scenario: a form submission in a Next.js app uses mutationOptions(boundAction) to submit, shows inline errors, and automatically invalidates related queries on success.

Quick Start

Use mutationOptions in your React component by wrapping your server action to enable consistent error handling and automatic cache management.

Frequently Asked Questions about safe-action-tanstack-query

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I handle errors from Next Safe Actions in TanStack Query mutations?▼

Bridging Next Safe Action results with TanStack Query mutations ensures consistent error modeling and client-side cache integration. It translates non-throwing action results into UseMutation-compatible data envelopes with type guards for server and validation errors.

How do I use TanStack Query optimistic updates with Next.js server actions?▼

You can enable TanStack Query optimistic updates with Next.js server actions by configuring onMutate, onError, and onSettled hooks. This integration manages robust error recovery and automatically invalidates related queries on success.

Can I use TanStack Query cache invalidation with Next Safe Action results?▼

Yes, bridging Next Safe Action results with TanStack Query enables automatic cache invalidation for related queries on success. It uses mutationOptions to connect non-throwing server action results directly to client-side mutation flows.

What is the best way to manage non-throwing server action constraints in TanStack Query?▼

The best way to manage non-throwing action constraints in TanStack Query is using mutationOptions() to map action outcomes. This provides ActionMutationError and type guards to handle server and validation errors without throwing exceptions.

How do I configure onSettled and onError hooks for Next Safe Action mutations?▼

You configure onSettled and onError hooks by wrapping your bound server action with mutationOptions(). This setup translates action outcomes for TanStack Query, enabling inline error display, navigation safety, and robust client-side error recovery.