React Query

Read and write data with useActionQuery and useActionMutation.

React Query

Install

terminal

pnpm add @zapaction/query @tanstack/react-query

Read with useActionQuery

useActionQuery requires readPolicy: "read-only" so reads stay explicit.

components/todo-panel.tsx

"use client";

import { useActionQuery } from "@zapaction/query";
import { listTodos } from "../app/actions";

const todosQuery = useActionQuery(listTodos, {
  input: {},
  queryKey: ["todos"],
  readPolicy: "read-only"
});

Write with useActionMutation

components/todo-panel.tsx

import { useActionMutation } from "@zapaction/query";
import { createTodo } from "../app/actions";

const createMutation = useActionMutation(createTodo, {
  invalidateOnSuccess: true
});

Keep query keys and tags aligned

app/query-keys.ts

import { createFeatureKeys, createFeatureTags } from "@zapaction/core";

export const todoKeys = createFeatureKeys("todos", {
  all: () => [],
  byUser: (userId: string) => ["by-user", userId]
});

export const todoTags = createFeatureTags("todos", {
  byUser: (userId: string) => ["by-user", userId]
});

Result preview

ui state

idle -> pending -> success | error

A clear state model makes retries and UX fallback logic easier to maintain.