Skip to content

NarixHine/uni-chem / .agents/skills/safe-action-hooks

safe-action-hooks

Verified

Use when executing next-safe-action actions from React client components -- useAction, useOptimisticAction, handling status/callbacks (onSuccess/onError/onSettled), execute vs executeAsync, or optimistic UI updates

FileKindSize
SKILL.mdskill md6.5 KB
optimistic-updates.mdmarkdown3.0 KB
status-callbacks.mdmarkdown5.2 KB
throw-on-navigation.mdmarkdown4.5 KB
use-action.mdmarkdown4.2 KB
use-state-action.mdmarkdown7.3 KB

status-callbacks.md

View on GitHub
# Status Lifecycle & Callbacks

## Status Lifecycle

```
idle → executing → hasSucceeded
                 → hasErrored
                 → hasNavigated
```

| Status | Meaning |
|---|---|
| `idle` | No execution has started (or `reset()` was called) |
| `executing` | Action promise is pending |
| `hasSucceeded` | Last execution returned `data` |
| `hasErrored` | Last execution had `serverError` or `validationErrors` |
| `hasNavigated` | Last execution triggered a navigation (redirect, notFound, etc.) |

## Shorthand Booleans

```ts
const {
  isIdle,          // status === "idle"
  isExecuting,     // status === "executing"
  isTransitioning, // React transition is still pending (after action resolves)
  isPending,       // isExecuting || isTransitioning
  hasSucceeded,    // status === "hasSucceeded"
  hasErrored,      // status === "hasErrored"
  hasNavigated,    // status === "hasNavigated"
} = useAction(myAction);
```

`isPending` is the most useful for disabling UI — it covers both the action execution and any React transition that follows. Note: `isTransitioning` tracks the React transition state separately (it may remain `true` briefly after `isExecuting` becomes `false`).

### Shorthand booleans as type guards

The hook return is a discriminated union keyed on `status`, and each of `isIdle` / `isExecuting` / `hasSucceeded` / `hasErrored` / `hasNavigated` is typed as literal `true` / `false` per branch. That makes them real type guards: checking one narrows `result` without further checks.

```ts
const action = useAction(myAction);

if (action.hasSucceeded) {
  action.result.data;        // Data (not Data | undefined)
  action.result.serverError; // undefined
} else if (action.hasErrored) {
  // result.serverError or result.validationErrors is the populated one
}
```

`isTransitioning` and `isPending` are plain `boolean` (they don't map to a single status branch) — they don't narrow.

## Callbacks

All callbacks are optional and receive typed arguments:

### onExecute

Fires immediately when `execute` or `executeAsync` is called.

```ts
useAction(myAction, {
  onExecute: ({ input }) => {
    console.log("Starting with input:", input);
  },
});
```

### onSuccess

Fires when the action returns data without errors.

```ts
useAction(myAction, {
  onSuccess: ({ data, input }) => {
    toast.success(`Created: ${data.name}`);
    router.refresh();
  },
});
```

### onError

Fires when the action has `serverError`, `validationErrors`, or throws.

```ts
useAction(myAction, {
  onError: ({ error, input }) => {
    // error.serverError    — from handleServerError
    // error.validationErrors — from schema validation / returnValidationErrors
    // error.thrownError    — non-navigation error thrown by executeAsync

    if (error.serverError) {
      toast.error(error.serverError);
    }
    if (error.validationErrors) {
      console.warn("Validation failed:", error.validationErrors);
    }
  },
});
```

### onNavigation

Fires when the action triggers a Next.js navigation error (redirect, notFound, forbidden, unauthorized).

```ts
useAction(myAction, {
  onNavigation: ({ input, navigationKind }) => {
    // navigationKind: "redirect" | "notFound" | "forbidden" | "unauthorized" | "other"
    console.log(`Navigation: ${navigationKind}`);
  },
});
```

### onSettled

Fires after any outcome (success, error, or navigation). Always runs.

```ts
useAction(myAction, {
  onSettled: ({ result, input, navigationKind }) => {
    // Good for cleanup, analytics, re-enabling UI
    setLoading(false);
  },
});
```

## Callback Execution Order

1. `onExecute` — immediately on execute
2. Action runs on server
3. One of: `onSuccess`, `onError`, or `onNavigation`
4. `onSettled` — always last

## throwOnNavigation Mode

When `throwOnNavigation: true` is set on a hook, `onNavigation` and `onSettled` callbacks are **not available**. TypeScript enforces this via a discriminated union:

```ts
// throwOnNavigation: true removes onNavigation and onSettled from the type
const { execute } = useAction(myAction, {
  throwOnNavigation: true,
  onExecute: () => { /* still works */ },
  onSuccess: ({ data }) => { /* still works */ },
  onError: ({ error }) => { /* still works */ },
  // onNavigation: () => {} // TypeScript error!
  // onSettled: () => {}    // TypeScript error!
});
```

Navigation errors are thrown during React's render phase to the nearest error boundary. In Next.js, this shows the appropriate error page (404, 403, 401).

**For side effects during navigation with `throwOnNavigation: true`**, use server-side action callbacks instead:

```ts
export const myAction = actionClient.action(
  async () => { redirect("/home"); },
  {
    onNavigation: async ({ navigationKind }) => { /* runs on server */ },
    onSettled: async ({ result }) => { /* runs on server */ },
  }
);
```

See [throwOnNavigation in depth](./throw-on-navigation.md) for full details.

## Using Multiple Callbacks

```tsx
const { execute, isPending, result } = useAction(createPost, {
  onExecute: () => {
    setFormDisabled(true);
  },
  onSuccess: ({ data }) => {
    toast.success("Post created!");
    router.push(`/posts/${data.id}`);
  },
  onError: ({ error }) => {
    toast.error(error.serverError ?? "Failed to create post");
  },
  onSettled: () => {
    setFormDisabled(false);
  },
});
```
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall