# AI skills (/docs/ai-skills)
next-safe-action provides a set of [skills](https://skills.sh), structured knowledge files optimized for AI coding agents. When installed, these skills give your AI agent deep context about next-safe-action's API, patterns, and anti-patterns, enabling it to write better code with the library.
## Installation [#installation]
Skills are installed via the `skills` CLI. Run from your project root:
```bash
npx skills add next-safe-action/skills
```
This downloads the skills into your project where AI agents can discover and use them automatically.
## Available Skills [#available-skills]
| Skill | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `safe-action-client` | Client creation, action definition, Standard Schema validation (Zod, Yup, Valibot), server error handling |
| `safe-action-middleware` | Authentication, authorization, logging, rate limiting, context extension, `createMiddleware()`, `useValidated()` post-validation middleware |
| `safe-action-hooks` | `useAction`, `useOptimisticAction`, status lifecycle, callbacks, `execute` vs `executeAsync` |
| `safe-action-forms` | React Hook Form adapter, native form submission, file uploads, bind arguments with forms |
| `safe-action-validation-errors` | `returnValidationErrors`, formatted vs flattened shapes, custom error shapes, `throwValidationErrors` |
| `safe-action-advanced` | Bind arguments, metadata schemas, framework errors (redirect/notFound/forbidden/unauthorized), type utilities |
| `safe-action-testing` | Vitest patterns for testing actions, middleware, hooks, validation errors, and framework errors |
| `safe-action-better-auth` | Better Auth adapter: `betterAuth()` middleware, typed session context, custom `authorize` callbacks, `unauthorized()` handling |
| `safe-action-tanstack-query` | TanStack Query adapter: `mutationOptions()`, `useMutation`, `ActionMutationError` handling, optimistic updates, query invalidation |
## How Skills Work [#how-skills-work]
Skills are markdown files that AI agents load when they detect a relevant task. Each skill contains:
* **Correct API usage** with complete, copy-paste-ready code examples
* **Anti-patterns** showing common mistakes and how to fix them
* **Type information** so the agent generates properly typed code
* **Sub-topic files** for deep dives into specific features
Unlike documentation (designed for humans to browse), skills are structured for AI agents to quickly find the right pattern and generate accurate code.
## Supported Agents [#supported-agents]
Skills work with any AI coding agent that supports the [skills.sh](https://skills.sh) format, including:
* [Claude Code](https://claude.ai/claude-code)
* [Cursor](https://cursor.com)
* [OpenAI Codex](https://openai.com/codex)
* Other agents that support the skills format
Visit [skills.sh](https://skills.sh) to learn more about the skills ecosystem.
# Contributing (/docs/contributing)
If you want to contribute to next-safe-action, please check out the [contributing guide](https://github.com/next-safe-action/next-safe-action/blob/main/CONTRIBUTING.md).
If you found bugs or just want to ask a question, feel free to open an issue or a discussion by following the [issue templates](https://github.com/next-safe-action/next-safe-action/issues/new/choose).
### Donations [#donations]
If you find this project useful, please consider making a [donation](https://github.com/sponsors/TheEdoRan). This is absolutely not required, but is very much appreciated, since it will help to cover the time and resources required to maintain this project. Thank you!
## Sponsors [#sponsors]
A big shout-out to all our [sponsors](https://github.com/sponsors/TheEdoRan)! You're the driving force behind this library's growth, and we're truly grateful for your support. ❤️
# Introduction (/docs/introduction)
**next-safe-action** is a library that takes the hassle out of Server Actions in Next.js. It gives you end-to-end type safety from input validation to the action result, with a chainable API for middleware, metadata, and schema validation, all powered by [Standard Schema](https://github.com/standard-schema/standard-schema).
## Features [#features]
Full TypeScript inference from input schema to action result, no manual type annotations needed.
Built-in input and output validation via Standard Schema (Zod, Valibot, ArkType, and more).
Chainable middleware with type-safe context accumulation for authentication, logging, and more.
Purpose-built hooks for executing actions with status tracking, callbacks, and optimistic updates.
## Why next-safe-action? [#why-next-safe-action]
Server Actions are powerful, but using them directly means writing a lot of boilerplate for validation, error handling, and type safety. Here's what changes with next-safe-action.
**Without next-safe-action**, raw Server Actions have no built-in validation or typed results:
```ts title="app/actions.ts"
"use server";
export async function updateUser(formData: FormData) {
// ❌ No type safety: raw FormData
const name = formData.get("name");
// ❌ Manual validation
if (typeof name !== "string" || name.length < 3) {
return { error: "Invalid name" };
}
// ❌ Untyped result: caller doesn't know the shape
try {
await db.user.update({ name });
return { success: true };
} catch (e) {
return { error: "Something went wrong" };
}
}
```
**With next-safe-action**, validation, type safety, and structured results out of the box:
```ts title="app/actions.ts"
"use server";
import { z } from "zod";
import { actionClient } from "@/lib/safe-action";
export const updateUser = actionClient
.inputSchema(z.object({ name: z.string().min(3) }))
.action(async ({ parsedInput: { name } }) => {
// ✅ `name` is typed as `string`, validated, min 3 chars
await db.user.update({ name });
// ✅ Return type is inferred and available to the caller
return { success: true };
});
```
The result is always a structured object with `data`, `validationErrors`, and `serverError`, making it impossible to forget error handling on the client side.
## Next steps [#next-steps]
Get up and running in 5 minutes with a complete working example.
Understand the action lifecycle, middleware pipeline, and architecture.
# Quick start (/docs/quick-start)
* Next.js >= 14 (App Router)
* React >= 18.2.0
* TypeScript >= 5
* A [Standard Schema](https://github.com/standard-schema/standard-schema) validation library (e.g., Zod, Valibot)
### Install [#install]
Install next-safe-action and a validation library:
npm
pnpm
yarn
bun
```bash
npm install next-safe-action zod
```
```bash
pnpm add next-safe-action zod
```
```bash
yarn add next-safe-action zod
```
```bash
bun add next-safe-action zod
```
npm
pnpm
yarn
bun
```bash
npm install next-safe-action valibot
```
```bash
pnpm add next-safe-action valibot
```
```bash
yarn add next-safe-action valibot
```
```bash
bun add next-safe-action valibot
```
Then, create a safe action client. This is the entry point for defining all your actions:
```ts title="src/lib/safe-action.ts"
import { createSafeActionClient } from "next-safe-action";
export const actionClient = createSafeActionClient();
```
This creates a base client with default settings. You can extend it later with [middleware](/docs/guides/middleware), [error handling](/docs/concepts/error-handling), and [metadata](/docs/advanced/metadata) as your app grows.
### Define an action [#define-an-action]
Create a Server Action with input validation. The schema guarantees that `parsedInput` is fully typed and validated before your server code runs:
```ts title="src/app/login-action.ts"
"use server";
import { z } from "zod";
import { actionClient } from "@/lib/safe-action";
const loginSchema = z.object({
username: z.string().min(3).max(10),
password: z.string().min(8).max(100),
});
export const loginUser = actionClient
.inputSchema(loginSchema)
.action(async ({ parsedInput: { username, password } }) => {
// `username` is string (3-10 chars), `password` is string (8-100 chars)
// Both are validated before this code runs
const user = await verifyCredentials(username, password);
return { id: user.id, name: user.name };
});
```
```ts title="src/app/login-action.ts"
"use server";
import * as v from "valibot";
import { actionClient } from "@/lib/safe-action";
const loginSchema = v.object({
username: v.pipe(v.string(), v.minLength(3), v.maxLength(10)),
password: v.pipe(v.string(), v.minLength(8), v.maxLength(100)),
});
export const loginUser = actionClient
.inputSchema(loginSchema)
.action(async ({ parsedInput: { username, password } }) => {
// `username` is string (3-10 chars), `password` is string (8-100 chars)
// Both are validated before this code runs
const user = await verifyCredentials(username, password);
return { id: user.id, name: user.name };
});
```
Note the `"use server"` directive at the top of the file. This is required by Next.js for all Server Actions.
The `action()` method returns a callable function. The `parsedInput` object is **fully typed** based on your schema, so you get autocomplete and compile-time errors if you access a field that doesn't exist.
### Execute from a client component [#execute-from-a-client-component]
The simplest approach. Call the action directly and handle the result:
```tsx title="src/app/login.tsx"
"use client";
import { loginUser } from "./login-action";
export default function Login() {
const handleLogin = async () => {
const result = await loginUser({
username: "johndoe",
password: "12345678",
});
// The result is a discriminated union, so checking one
// field narrows the others to `undefined`.
if (result.data) {
console.log("Welcome,", result.data.name);
} else if (result.validationErrors) {
console.log("Validation failed:", result.validationErrors);
} else if (result.serverError) {
console.log("Server error:", result.serverError);
}
};
return ;
}
```
For richer UI, track execution status, handle callbacks, and more:
```tsx title="src/app/login.tsx"
"use client";
import { useAction } from "next-safe-action/hooks";
import { loginUser } from "./login-action";
export default function Login() {
const { execute, result, isExecuting } = useAction(loginUser, {
onSuccess: ({ data }) => {
console.log("Welcome,", data.name);
},
onError: ({ error }) => {
console.log("Something went wrong:", error);
},
});
return (
);
}
```
The `useAction` hook gives you reactive `status`, `result`, and `input` values, plus lifecycle callbacks (`onSuccess`, `onError`, `onSettled`, and more). See the [Hooks guide](/docs/guides/hooks) for the full API.
## What's next? [#whats-next]
Understand the full action lifecycle and middleware pipeline.
Learn the full structure of the result object and how to handle every case.
Add authentication, logging, and context to your actions.
Deep dive into useAction with status tracking, callbacks, and async execution.
# Troubleshooting (/docs/troubleshooting)
Common issues and their solutions. Click on an issue to expand the answer.
If you use next-safe-action in a monorepo, you may see this error:
```
Type error: The inferred type of 'action' cannot be named without a reference to '...'.
This is likely not portable. A type annotation is necessary.
```
**Fix:** Set `baseUrl` in your `tsconfig.json`:
```json title="tsconfig.json"
{
"compilerOptions": {
"baseUrl": "."
}
}
```
Find more information in [this GitHub issue](https://github.com/next-safe-action/next-safe-action/issues/64).
This usually means one of:
1. **You're on v7.1.3 or earlier**, these versions used TypeSchema, which had inference issues with TypeScript >= 5.5. Upgrade to v7.2.0+ where Standard Schema replaced TypeSchema.
2. **Your schema library doesn't implement Standard Schema v1**, make sure you're using a compatible version of Zod (3.23+), Valibot (1.0+), or ArkType (2.0+). See [Standard Schema](/docs/integrations/standard-schema) for details.
3. **Missing `"strict": true`** in your `tsconfig.json`, next-safe-action relies on strict mode for correct inference.
If you're on v7.1.3 or earlier, this was a known issue with TypeSchema's dynamic imports. **Upgrade to v7.2.0+** where Standard Schema replaced TypeSchema. Standard Schema works with all runtimes.
On v7.2.0+, Edge Runtime is fully supported.
`redirect()` works inside actions, but it behaves differently than you might expect:
* `redirect()` throws a special error internally. next-safe-action catches it and re-throws it so Next.js can handle the navigation.
* **`onSuccess` does NOT fire** when `redirect()` is called. Use `onNavigation` instead.
* When calling actions directly (not via hooks), code after `redirect()` never executes.
See [Framework Errors](/docs/advanced/framework-errors) for the full guide on `redirect()`, `notFound()`, `forbidden()`, and `unauthorized()`.
If you're contributing to the docs and see component resolution errors, make sure your `app/docs/[...slug]/page.tsx` uses `useMDXComponents({})` from `@/mdx-components` instead of `defaultMdxComponents`:
```tsx
import { useMDXComponents } from "@/mdx-components";
// In your page component:
```
The explicit `components` prop takes precedence over the `useMDXComponents` fallback in `mdx-components.tsx`.
`handleServerError` always receives an `Error` object. If your action code throws a non-Error value (like a string), it will be wrapped in a generic `Error`.
To use custom error classes:
```ts
class DatabaseError extends Error {
constructor(message: string) {
super(message);
this.name = "DatabaseError";
}
}
const actionClient = createSafeActionClient({
handleServerError: (error) => {
if (error instanceof DatabaseError) {
return "Database error occurred";
}
return DEFAULT_SERVER_ERROR_MESSAGE;
},
});
```
See [Error Handling](/docs/concepts/error-handling) for the full error taxonomy and [Error Classes](/docs/api/error-classes) for all exported error types.
Hook callbacks fire based on status transitions, not on every render. Common issues:
1. **`onSuccess` fires on mount**, this can happen if `result` already has data from a previous execution. Call `reset()` when appropriate.
2. **`onSettled` fires twice**, this shouldn't happen. Check that you're not rendering the component that calls `useAction` twice (e.g., in React Strict Mode, callbacks may appear to fire twice in development).
3. **`onSuccess` doesn't fire after redirect**, this is by design. When `redirect()` is called, `onNavigation` fires instead. See [Framework Errors](/docs/advanced/framework-errors).
See [Hooks](/docs/guides/hooks) for callback lifecycle details and [Hooks API](/docs/api/hooks-api) for the full reference.
When using form actions (stateless `
## Still stuck? [#still-stuck]
If your issue isn't listed here:
* Search [existing GitHub issues](https://github.com/next-safe-action/next-safe-action/issues)
* Open a [new issue](https://github.com/next-safe-action/next-safe-action/issues/new/choose) with a minimal reproduction
* Start a [GitHub discussion](https://github.com/next-safe-action/next-safe-action/discussions) for questions
# Bind arguments (/docs/advanced/bind-arguments)
Bind arguments let you pass **extra validated arguments** to an action that aren't part of the main input. This is useful when you need to combine server-side values (like an ID from a Server Component) with client-side input (like form data).
## How it works [#how-it-works]
### Define bind args schemas [#define-bind-args-schemas]
Use `.bindArgsSchemas()` to define schemas for the extra arguments. The schemas are passed as a **named tuple** so TypeScript can track each argument's type:
```ts title="src/app/actions.ts"
"use server";
import { z } from "zod";
import { actionClient } from "@/lib/safe-action";
export const updateItem = actionClient
.bindArgsSchemas<[itemId: z.ZodString]>([z.string().uuid()])
.inputSchema(z.object({ name: z.string().min(1) }))
.action(async ({ parsedInput, bindArgsParsedInputs: [itemId] }) => {
// itemId is typed as string (validated UUID)
// parsedInput.name is typed as string
await db.item.update({ where: { id: itemId }, data: { name: parsedInput.name } });
return { success: true };
});
```
### Bind and call from the client [#bind-and-call-from-the-client]
Use JavaScript's `.bind()` to attach the extra arguments:
```tsx title="src/app/items/[id]/page.tsx"
import { updateItem } from "./actions";
import { ItemForm } from "./item-form";
// Server Component: has access to the item ID
export default async function ItemPage({ params }: { params: { id: string } }) {
// Bind the item ID to the action
const updateThisItem = updateItem.bind(null, params.id);
return ;
}
```
```tsx title="src/app/items/[id]/item-form.tsx"
"use client";
import { useAction } from "next-safe-action/hooks";
export function ItemForm({ action }: { action: typeof updateItem }) {
const { execute, isExecuting } = useAction(action);
return (
);
}
```
**Why use bind args instead of including the ID in the input?** Bind args are set on the server (in a Server Component) and can't be tampered with by the client. This is a security pattern, the client only sends the input, not the ID.
## Named tuple types [#named-tuple-types]
The generic parameter `<[itemId: z.ZodString]>` creates a **named tuple type**. This gives you readable names when destructuring `bindArgsParsedInputs`:
```ts
// Without named tuple: positional, harder to read
.bindArgsSchemas([z.string(), z.number()])
.action(async ({ bindArgsParsedInputs: [arg0, arg1] }) => { ... })
// With named tuple: self-documenting
.bindArgsSchemas<[itemId: z.ZodString, version: z.ZodNumber]>([z.string(), z.number()])
.action(async ({ bindArgsParsedInputs: [itemId, version] }) => { ... })
```
## Progressive enhancement [#progressive-enhancement]
Bind args work with form actions too. The bound values are sent as hidden fields in the `FormData`:
```tsx
// Server Component
const deleteItem = deleteItemAction.bind(null, item.id);
// Client form: works without JavaScript
```
## See also [#see-also]
* [Action result](/docs/concepts/action-result): how bind args validation errors appear in the result
* [`.bindArgsSchemas()` method](/docs/api/safe-action-client#bindargsschemas): API reference
* [Form actions](/docs/guides/form-actions): using bind args with progressive enhancement
# Custom validation errors (/docs/advanced/custom-validation-errors)
next-safe-action gives you control over how validation errors are shaped, formatted, and returned to the client.
## Error shapes [#error-shapes]
There are two built-in shapes:
The formatted shape mirrors the schema structure with `_errors` arrays at each level:
```ts
// Result of failed validation:
{
validationErrors: {
name: { _errors: ["String must contain at least 2 character(s)"] },
address: {
street: { _errors: ["Required"] },
_errors: [],
},
}
}
```
This is the default because it preserves the nesting of your schema, making it easy to display errors next to the corresponding form fields.
The flattened shape separates form-level errors from field-level errors:
```ts
// Result of failed validation:
{
validationErrors: {
formErrors: ["Passwords don't match"],
fieldErrors: {
name: ["String must contain at least 2 character(s)"],
email: ["Invalid email"],
},
}
}
```
This is simpler to work with when you just need a list of errors per field.
### Setting the default shape [#setting-the-default-shape]
Set the shape for all actions when creating the client:
```ts
const actionClient = createSafeActionClient({
defaultValidationErrorsShape: "flattened",
});
```
### Overriding per action [#overriding-per-action]
Override the shape for a specific action by passing a function to `inputSchema()`:
```ts
export const myAction = actionClient
.inputSchema(schema, {
handleValidationErrorsShape: (ve) => flattenValidationErrors(ve),
})
.action(async ({ parsedInput }) => { /* ... */ });
```
## Manually returning validation errors [#manually-returning-validation-errors]
Use `returnValidationErrors()` to return validation errors from your server code, for example when checking business logic that can't be expressed in a schema:
```ts
import { returnValidationErrors } from "next-safe-action";
export const signUp = actionClient
.inputSchema(z.object({
email: z.string().email(),
username: z.string().min(3),
}))
.action(async ({ parsedInput }) => {
// Check business logic
const emailExists = await db.user.findByEmail(parsedInput.email);
if (emailExists) {
return returnValidationErrors(schema, {
email: { _errors: ["Email already registered"] },
});
}
const usernameExists = await db.user.findByUsername(parsedInput.username);
if (usernameExists) {
return returnValidationErrors(schema, {
username: { _errors: ["Username taken"] },
});
}
// Create user...
});
```
`returnValidationErrors` actually **throws** internally, it never returns. This ensures the remaining server code doesn't execute. The error is caught by the action builder and returned as `validationErrors` in the result.
### Form-level errors [#form-level-errors]
Use `_errors` at the root level for errors that don't belong to a specific field:
```ts
return returnValidationErrors(schema, {
_errors: ["Invalid credentials"],
});
```
## Throwing validation errors [#throwing-validation-errors]
If you prefer throwing validation errors instead of returning them in the result, enable `throwValidationErrors`:
```ts
// Per action
export const myAction = actionClient
.action(async ({ parsedInput }, { throwValidationErrors }) => {
// This throws instead of returning in the result
throwValidationErrors(schema, {
email: { _errors: ["Already registered"] },
});
});
// Globally (all actions throw on validation failure)
const actionClient = createSafeActionClient({
throwValidationErrors: true,
});
```
## Utility functions [#utility-functions]
| Function | Description |
| ---------------------------------------- | -------------------------------------------------- |
| `flattenValidationErrors(ve)` | Convert formatted errors to flattened shape |
| `formatValidationErrors(ve)` | Identity function (returns formatted errors as-is) |
| `returnValidationErrors(schema, errors)` | Throw validation errors from server code |
See the [Validation Utilities API reference](/docs/api/validation-utilities) for full signatures.
## See also [#see-also]
* [Error handling](/docs/concepts/error-handling): the complete error taxonomy
* [Input validation](/docs/concepts/input-validation): how validation errors are generated
* [Error classes](/docs/api/error-classes): `ActionValidationError` and related classes
# Extend schemas (/docs/advanced/extend-schemas)
The `.inputSchema()` method can accept an **async function** instead of a direct schema. This function receives the previous schema (if any) as an argument, letting you build on top of it. This is useful for creating action templates that share a base schema.
## Basic usage [#basic-usage]
Pass an async function to `inputSchema()` that returns a new schema:
```ts title="src/lib/safe-action.ts"
import { z } from "zod";
import { actionClient } from "@/lib/safe-action";
// Template: all CRUD actions need an ID
const crudClient = actionClient
.inputSchema(z.object({ id: z.string().uuid() }));
// Extend: update action adds name and email
export const updateUser = crudClient
.inputSchema(async (prevSchema) => {
// prevSchema is z.object({ id: z.string().uuid() })
return prevSchema.extend({
name: z.string().min(2),
email: z.string().email(),
});
})
.action(async ({ parsedInput }) => {
// parsedInput is typed as { id: string, name: string, email: string }
});
```
## Multiple extensions [#multiple-extensions]
You can chain multiple `inputSchema()` calls, each building on the last:
```ts
const baseAction = actionClient
.inputSchema(z.object({ orgId: z.string() }));
const teamAction = baseAction
.inputSchema(async (prevSchema) => {
return prevSchema.extend({ teamId: z.string() });
});
const memberAction = teamAction
.inputSchema(async (prevSchema) => {
return prevSchema.extend({ memberId: z.string() });
})
.action(async ({ parsedInput }) => {
// parsedInput: { orgId: string, teamId: string, memberId: string }
});
```
The async function signature is key, as it lets you `await` other operations before returning the schema. This is useful for [i18n](/docs/advanced/i18n) where you need to load translations before building the schema.
## Use cases [#use-cases]
* **CRUD templates**: Define a base schema with an ID field, then extend for create/update
* **Multi-tenant apps**: Start with `orgId`, extend with resource-specific fields
* **i18n validation**: Await translations before defining error messages in schemas
## See also [#see-also]
* [Input validation](/docs/concepts/input-validation): foundational guide to schema validation
* [i18n](/docs/advanced/i18n): combine async schemas with translation loading
* [`.inputSchema()` method](/docs/api/safe-action-client#inputschema): API reference for the async factory signature
# File uploads (/docs/advanced/file-uploads)
You can upload files through safe actions using `FormData` input. This guide shows how to validate and process file uploads.
* Node.js >= 20 (for native `File` support)
* Next.js default body size limit is **1 MB**. For larger files, configure `bodyParser` in your route or use a separate upload endpoint.
### Install zod-form-data [#install-zod-form-data]
npm
pnpm
yarn
bun
```bash
npm install zod-form-data
```
```bash
pnpm add zod-form-data
```
```bash
yarn add zod-form-data
```
```bash
bun add zod-form-data
```
### Define the upload action [#define-the-upload-action]
Use `zod-form-data` to validate the `FormData` input, including file fields:
```ts title="src/app/actions.ts"
"use server";
import { z } from "zod";
import { zfd } from "zod-form-data";
import { actionClient } from "@/lib/safe-action";
const uploadSchema = zfd.formData({
name: zfd.text(z.string().min(1)),
file: zfd.file(z.instanceof(File).refine(
(f) => f.size < 1_000_000,
"File must be under 1MB"
)),
});
export const uploadFile = actionClient
.inputSchema(uploadSchema)
.action(async ({ parsedInput: { name, file } }) => {
// `file` is a validated File object
const bytes = await file.arrayBuffer();
const buffer = Buffer.from(bytes);
// Save to disk, S3, etc.
await saveFile(name, buffer);
return { fileName: file.name, size: file.size };
});
```
### Create the upload form [#create-the-upload-form]
```tsx title="src/app/upload.tsx"
"use client";
import { useAction } from "next-safe-action/hooks";
import { useRef } from "react";
import { uploadFile } from "./actions";
export default function UploadForm() {
const formRef = useRef(null);
const { execute, result, isExecuting } = useAction(uploadFile, {
onSuccess: ({ data }) => {
alert(`Uploaded ${data.fileName} (${data.size} bytes)`);
formRef.current?.reset();
},
});
return (
);
}
```
## Multiple files [#multiple-files]
For multiple file uploads, use an array schema:
```ts
const schema = zfd.formData({
files: zfd.repeatableOfType(
zfd.file(z.instanceof(File).refine((f) => f.size < 5_000_000, "Max 5MB per file"))
),
});
```
Remember the 1MB default body size limit in Next.js. For larger uploads, consider using presigned URLs (S3, Cloudflare R2) instead of sending files through Server Actions.
## See also [#see-also]
* [Form actions](/docs/guides/form-actions): using FormData with server actions
* [Hooks](/docs/guides/hooks): the `useAction` hook used in the upload form example
* [Input validation](/docs/concepts/input-validation): how `zod-form-data` integrates with Standard Schema
# Framework navigation/errors (/docs/advanced/framework-errors)
Next.js provides navigation functions like `redirect()`, `notFound()`, `forbidden()`, and `unauthorized()`. These work inside safe actions, and next-safe-action detects and handles them automatically.
## How framework errors work [#how-framework-errors-work]
When you call a navigation function inside an action, Next.js throws a special error internally. next-safe-action:
1. **Catches** the error and identifies it as a framework error
2. **Re-throws** it so Next.js can handle the actual navigation
3. **Notifies** hooks via `onNavigation` callback and `hasNavigated` status
```ts title="src/app/actions.ts"
"use server";
import { redirect } from "next/navigation";
import { actionClient } from "@/lib/safe-action";
export const loginAction = actionClient
.inputSchema(loginSchema)
.action(async ({ parsedInput }) => {
const user = await authenticate(parsedInput);
if (!user) {
// Return validation error, NOT a framework error
return returnValidationErrors(loginSchema, {
_errors: ["Invalid credentials"],
});
}
// This is a framework error: triggers navigation
redirect("/dashboard");
});
```
## Navigation kinds [#navigation-kinds]
Each navigation function maps to a `navigationKind`:
| Function | `navigationKind` | HTTP Status | Description |
| ---------------- | ---------------- | ----------- | -------------------------- |
| `redirect(url)` | `"redirect"` | 303/307/308 | Navigate to another page |
| `notFound()` | `"notFound"` | 404 | Show the not-found page |
| `forbidden()` | `"forbidden"` | 403 | Show the forbidden page |
| `unauthorized()` | `"unauthorized"` | 401 | Show the unauthorized page |
## Handling in hooks [#handling-in-hooks]
By default, `useAction` catches navigation errors and sets the status to `"hasNavigated"`, firing the `onNavigation` callback. The component stays mounted:
```tsx
const { execute, hasNavigated } = useAction(loginAction, {
onNavigation: ({ navigationKind }) => {
if (navigationKind === "redirect") {
// The user was redirected
} else if (navigationKind === "notFound") {
// The resource wasn't found
}
},
onSuccess: ({ data }) => {
// This does NOT fire when redirect() is called
// redirect is a navigation, not a success
},
});
```
### `throwOnNavigation: true` [#throwonnavigation-true]
Set `throwOnNavigation` to `true` to propagate navigation errors to the nearest error boundary. In Next.js, this shows the appropriate error page:
* `notFound()` shows the not-found page
* `forbidden()` shows the forbidden page
* `unauthorized()` shows the unauthorized page
* `redirect()` performs the redirect (via HTTP headers)
```tsx
// Navigation errors propagate to Next.js error boundaries
const { execute } = useAction(loginAction, {
throwOnNavigation: true,
});
```
When `throwOnNavigation` is `true`, `onNavigation` and `onSettled` callbacks are **not available**. TypeScript will prevent you from passing them. This is because they cannot execute: see [why callbacks can't fire](#why-callbacks-cant-fire-with-throwonnavigation-true) below.
When `redirect()` is called in an action, `onSuccess` does **not** fire regardless of `throwOnNavigation`. If your action redirects after success, put cleanup logic in `onNavigation` or `onSettled` (with default `throwOnNavigation`), or use server-side action callbacks.
### Why callbacks can't fire with `throwOnNavigation: true` [#why-callbacks-cant-fire-with-throwonnavigation-true]
When `throwOnNavigation` is `true`, the navigation error is thrown during React's **render phase** to reach the error boundary. This is a fundamental constraint of React's rendering model, not a library limitation:
1. **React's render must be pure.** The render phase is where React calls your component function. It must be synchronous and side-effect free.
2. **Effects only run after commit.** `useEffect` and `useLayoutEffect` callbacks are scheduled during render but only execute during the **commit phase**, after React has successfully rendered the component.
3. **A render-phase throw prevents commit.** When a component throws during render, React never reaches the commit phase for that component. All scheduled effects are discarded.
4. **The error boundary catches the throw.** React propagates the error to the nearest error boundary, which unmounts the throwing component and renders its fallback.
Since `onNavigation` and `onSettled` are fired via `useEffect`, they can never execute when the render throws. There is no React API that allows committed side effects from a component whose render fails.
**For side effects that must run on navigation** (analytics, logging, cleanup), use server-side action callbacks instead. These run on the server before the error reaches the client, and are guaranteed to complete:
```ts
export const myAction = actionClient
.inputSchema(schema)
.action(
async ({ parsedInput }) => {
notFound();
},
{
onNavigation: async ({ navigationKind }) => {
// Guaranteed to run on the server
await analytics.track("navigation", { navigationKind });
},
}
);
```
## Handling in action callbacks [#handling-in-action-callbacks]
Framework navigation/errors also work with server-side action callbacks:
```ts
export const myAction = actionClient
.inputSchema(schema)
.action(
async ({ parsedInput }) => {
redirect("/somewhere");
},
{
onNavigation: ({ navigationKind }) => {
// Runs on the server after navigation is triggered
console.log("Action navigated:", navigationKind);
},
}
);
```
## Direct execution [#direct-execution]
When calling actions directly (not via hooks), framework errors cause the navigation to happen on the server. The function call never returns a result:
```tsx
const result = await loginAction(input);
// If redirect() was called, this line never executes
// The browser navigates to the redirect URL instead
```
## See also [#see-also]
* [Error handling](/docs/concepts/error-handling): where framework errors fit in the error taxonomy
* [Hooks](/docs/guides/hooks): `onNavigation` callback and `hasNavigated` status
* [ActionCallbacks](/docs/api/safe-action-client#actioncallbacks-action-callbacks): server-side `onNavigation` callback
# Internationalization (i18n) (/docs/advanced/i18n)
next-safe-action supports async schema functions, which lets you load translations before building your validation schema. This means validation error messages can be in the user's language.
## How it works [#how-it-works]
Instead of passing a schema directly to `inputSchema()`, pass an **async function** that returns a schema. This function runs on the server before validation, giving you a chance to load translations:
### Set up the async schema [#set-up-the-async-schema]
```ts title="src/app/actions.ts"
"use server";
import { z } from "zod";
import { actionClient } from "@/lib/safe-action";
import { getTranslations } from "@/lib/i18n";
export const createUser = actionClient
.inputSchema(async () => {
// Load translations for the current locale
const t = await getTranslations("validation");
return z.object({
name: z.string().min(2, t("name.tooShort")),
email: z.string().email(t("email.invalid")),
age: z.number().min(18, t("age.tooYoung")),
});
})
.action(async ({ parsedInput }) => {
// parsedInput is typed based on the returned schema
await db.user.create({ data: parsedInput });
});
```
### Use with your i18n library [#use-with-your-i18n-library]
This works with any i18n solution, including `next-intl`, `i18next`, `react-i18next`, custom solutions, etc. The only requirement is that the translation function is available server-side:
```ts
// next-intl example
import { getTranslations } from "next-intl/server";
.inputSchema(async () => {
const t = await getTranslations("validation");
return z.object({
name: z.string().min(2, t("name.min")),
});
})
```
The async function runs **every time** the action is called, so it always uses the current locale. This is important because the locale might change between calls.
## Combining with schema extension [#combining-with-schema-extension]
You can combine i18n with [schema extension](/docs/advanced/extend-schemas) to build on a base schema:
```ts
const baseClient = actionClient
.inputSchema(z.object({ orgId: z.string() }));
export const createTeam = baseClient
.inputSchema(async (prevSchema) => {
const t = await getTranslations("validation");
return prevSchema.extend({
teamName: z.string().min(3, t("teamName.tooShort")),
});
})
.action(async ({ parsedInput }) => {
// parsedInput: { orgId: string, teamName: string }
});
```
## See also [#see-also]
* [Extend schemas](/docs/advanced/extend-schemas): the async schema factory pattern used by i18n
* [Input validation](/docs/concepts/input-validation): foundational guide to schema validation
* [Standard Schema](/docs/integrations/standard-schema): validation libraries compatible with i18n
# Metadata (/docs/advanced/metadata)
Metadata lets you attach **type-safe data** to each action that's accessible in middleware. This is useful for logging, permission checks, rate limiting, and any cross-cutting concern that needs to know *which* action is running.
## Setup [#setup]
### Define a metadata schema [#define-a-metadata-schema]
Tell the client what shape metadata should have:
```ts title="src/lib/safe-action.ts"
import { z } from "zod";
import { createSafeActionClient } from "next-safe-action";
export const actionClient = createSafeActionClient({
defineMetadataSchema() {
return z.object({
actionName: z.string(),
requiredRole: z.enum(["user", "admin"]).optional(),
});
},
});
```
### Set metadata on each action [#set-metadata-on-each-action]
Once a metadata schema is defined, `.metadata()` must be called before `.action()`:
```ts title="src/app/actions.ts"
"use server";
export const deleteUser = actionClient
.metadata({ actionName: "deleteUser", requiredRole: "admin" })
.inputSchema(z.object({ userId: z.string() }))
.action(async ({ parsedInput }) => {
await db.user.delete({ where: { id: parsedInput.userId } });
});
```
TypeScript enforces the metadata shape. If you forget a required field or use the wrong type, you get a compile error.
### Access metadata in middleware [#access-metadata-in-middleware]
Metadata is available in every middleware function:
```ts title="src/lib/safe-action.ts"
export const actionClient = createSafeActionClient({
defineMetadataSchema() {
return z.object({
actionName: z.string(),
requiredRole: z.enum(["user", "admin"]).optional(),
});
},
}).use(async ({ next, metadata }) => {
// Log which action is running
console.log(`Running action: ${metadata.actionName}`);
return next();
}).use(async ({ next, metadata, ctx }) => {
// Check permissions based on metadata
if (metadata.requiredRole && ctx.user.role !== metadata.requiredRole) {
throw new Error(`Requires ${metadata.requiredRole} role`);
}
return next();
});
```
## Use cases [#use-cases]
| Use case | Metadata fields |
| ------------- | ------------------------------------- |
| Logging | `actionName`, `category` |
| Permissions | `requiredRole`, `requiredPermissions` |
| Rate limiting | `rateLimit`, `rateLimitWindow` |
| Feature flags | `feature`, `experimentGroup` |
| Analytics | `trackingEvent`, `source` |
Metadata is validated at runtime using the schema you define. If invalid metadata is passed, the action fails with a metadata validation error before any middleware runs.
## See also [#see-also]
* [Middleware](/docs/guides/middleware): where metadata is most commonly used
* [`defineMetadataSchema`](/docs/api/create-safe-action-client#parameters): client-level metadata schema configuration
* [`.metadata()` method](/docs/api/safe-action-client#metadata): API reference
* [`ActionMetadataValidationError`](/docs/api/error-classes#actionmetadatavalidationerror): error thrown on invalid metadata
# Output validation (/docs/advanced/output-validation)
By default, the return type of your server code is inferred by TypeScript. But if you want **runtime validation** of the output, ensuring your server code returns exactly the expected shape, use `outputSchema()`.
## Why validate output? [#why-validate-output]
* **Contract enforcement**: Guarantee the shape of data sent to the client, even as server code evolves
* **Type safety from schema**: The `data` type in the result comes from the output schema, not the function return type
* **Defense in depth**: Catch bugs where server code accidentally returns extra or missing fields
## Usage [#usage]
### Define an output schema [#define-an-output-schema]
Chain `.outputSchema()` before `.action()`:
```ts title="src/app/actions.ts"
"use server";
import { z } from "zod";
import { actionClient } from "@/lib/safe-action";
const outputSchema = z.object({
id: z.string(),
name: z.string(),
email: z.string().email(),
});
export const getUser = actionClient
.inputSchema(z.object({ userId: z.string() }))
.outputSchema(outputSchema)
.action(async ({ parsedInput }) => {
const user = await db.user.findUnique({ where: { id: parsedInput.userId } });
// TypeScript ensures this matches outputSchema
return { id: user.id, name: user.name, email: user.email };
});
```
### Handle output validation errors [#handle-output-validation-errors]
If your server code returns data that doesn't match the output schema, the action fails with a server error (not a validation error, since output issues are server-side bugs):
```ts
// If the server code returns { id: 123, name: "Alice" } (missing email),
// the action returns:
// { serverError: "Something went wrong" }
```
The actual `ActionOutputDataValidationError` is caught by `handleServerError`, so you can log it:
```ts
const actionClient = createSafeActionClient({
handleServerError(e) {
if (e.constructor.name === "ActionOutputDataValidationError") {
console.error("Output validation failed:", e.message);
}
return "Something went wrong";
},
});
```
Schema **transforms and defaults are applied**: just like input validation, the returned `data` (and the `data` received by server-side `onSuccess`/`onSettled` callbacks) is the parsed output of the schema, not the raw return value. A Zod `.transform()` or `.default()` in the output schema takes effect on the client.
Output validation is optional and most useful for API-like actions where the contract between server and client must be strict. For internal UI actions, TypeScript inference is usually sufficient.
## See also [#see-also]
* [Input validation](/docs/concepts/input-validation): validate what goes *in* to the action
* [`.outputSchema()` method](/docs/api/safe-action-client#outputschema): API reference
* [`ActionOutputDataValidationError`](/docs/api/error-classes#actionoutputdatavalidationerror): error class thrown on output mismatch
# Standalone middleware (/docs/advanced/standalone-middleware)
The `createMiddleware()` helper lets you define middleware functions **outside** of a client, with proper type constraints. This is useful for sharing middleware across multiple clients or publishing middleware as a package.
## Why standalone middleware? [#why-standalone-middleware]
When you define middleware inline with `.use()`, the types are inferred from the client chain. But if you want to define middleware in a separate file, or share it across clients, you need a way to declare the type requirements upfront. That's what `createMiddleware()` does.
## Usage [#usage]
```ts title="src/lib/middleware/logging.ts"
import { createMiddleware } from "next-safe-action";
export const loggingMiddleware = createMiddleware().define(async ({ next, metadata }) => {
const start = Date.now();
const result = await next();
console.log(`Action took ${Date.now() - start}ms`, metadata);
return result;
});
```
Then use it with any client:
```ts title="src/lib/safe-action.ts"
import { createSafeActionClient } from "next-safe-action";
import { loggingMiddleware } from "./middleware/logging";
export const actionClient = createSafeActionClient().use(loggingMiddleware);
```
## Type constraints [#type-constraints]
If your middleware needs specific properties on the context, server error, or metadata, declare them as a generic:
```ts title="src/lib/middleware/auth-guard.ts"
import { createMiddleware } from "next-safe-action";
// This middleware requires ctx to have a `user` property
export const adminGuard = createMiddleware<{
ctx: { user: { role: string } };
}>().define(async ({ next, ctx }) => {
if (ctx.user.role !== "admin") {
throw new Error("Admin access required");
}
return next();
});
```
Now TypeScript will error if you try to use `adminGuard` on a client that doesn't have `user` in its context:
```ts
// ✅ Works: authClient has ctx.user from auth middleware
const adminClient = authClient.use(adminGuard);
// ❌ Type error: actionClient doesn't have ctx.user
const broken = actionClient.use(adminGuard);
```
## Available constraints [#available-constraints]
The generic parameter accepts these optional properties:
| Property | Type | Description |
| ------------- | ----------------- | ----------------------------- |
| `ctx` | `object` | Required shape of the context |
| `metadata` | `Schema` | Required shape of metadata |
| `serverError` | `string \| Error` | Required server error type |
```ts
createMiddleware<{
ctx: { user: { id: string; role: string } };
metadata: { actionName: string };
}>().define(async ({ next, ctx, metadata }) => {
// ctx.user and metadata.actionName are typed
return next();
});
```
The constraint defines the **minimum** required shape. The actual context/metadata can have additional properties, the middleware just needs these to be present.
## Standalone validated middleware [#standalone-validated-middleware]
The `createValidatedMiddleware()` helper works like `createMiddleware()`, but for middleware that runs **after** input validation via `useValidated()`. It lets you declare type constraints for `parsedInput`, `clientInput`, and bind args in addition to `ctx` and `metadata`.
### Why standalone validated middleware? [#why-standalone-validated-middleware]
Just as `createMiddleware()` lets you share pre-validation middleware across clients, `createValidatedMiddleware()` lets you share post-validation middleware. This is especially useful for authorization patterns that depend on input shape.
### Usage [#usage-1]
```ts title="src/lib/middleware/check-ownership.ts"
import { createValidatedMiddleware } from "next-safe-action";
export const checkOwnership = createValidatedMiddleware<{
ctx: { user: { id: string } };
parsedInput: { resourceId: string };
}>().define(async ({ parsedInput, ctx, next }) => {
const resource = await db.resource.findUnique({
where: { id: parsedInput.resourceId },
});
if (resource?.ownerId !== ctx.user.id) {
throw new Error("Not authorized");
}
return next({ ctx: { resource } });
});
```
Then use it with any client that has the required context and schema:
```ts title="src/app/actions.ts"
import { checkOwnership } from "@/lib/middleware/check-ownership";
export const updateResource = authClient
.inputSchema(z.object({ resourceId: z.string(), title: z.string() }))
.useValidated(checkOwnership)
.action(async ({ ctx }) => {
// ctx.resource is typed and available
});
```
### Available constraints [#available-constraints-1]
The generic parameter accepts all properties from `createMiddleware()` plus:
| Property | Type | Description |
| ---------------------- | -------------------- | ------------------------------------- |
| `ctx` | `object` | Required shape of the context |
| `metadata` | `Schema` | Required shape of metadata |
| `serverError` | `string \| Error` | Required server error type |
| `parsedInput` | `unknown` | Required shape of validated input |
| `clientInput` | `unknown` | Required shape of raw client input |
| `bindArgsParsedInputs` | `readonly unknown[]` | Required shape of validated bind args |
| `bindArgsClientInputs` | `readonly unknown[]` | Required shape of raw bind args |
The constraint defines the **minimum** required shape. The actual input can have additional properties: the middleware just needs these to be present.
## See also [#see-also]
* [Middleware guide](/docs/guides/middleware): foundational middleware concepts and patterns
* [`createMiddleware()` API](/docs/api/create-middleware): full API reference
* [`createValidatedMiddleware()` API](/docs/api/create-validated-middleware): full API reference for validated standalone middleware
* [Validated middleware guide](/docs/guides/middleware#validated-middleware): when and how to use `useValidated()`
* [Metadata](/docs/advanced/metadata): use metadata constraints in standalone middleware
# Action client (/docs/concepts/action-client)
The **safe action client** is the starting point for defining all your actions. You create one with `createSafeActionClient()`, then use its chainable methods to add middleware, input schemas, and server code.
## Creating a client [#creating-a-client]
```ts title="src/lib/safe-action.ts"
import { createSafeActionClient } from "next-safe-action";
export const actionClient = createSafeActionClient();
```
This creates a client with sensible defaults. You can customize its behavior by passing options, see the [API reference](/docs/api/create-safe-action-client) for the full list.
### Common options [#common-options]
```ts title="src/lib/safe-action.ts"
import { createSafeActionClient } from "next-safe-action";
export const actionClient = createSafeActionClient({
// Customize how server errors are handled and what's sent to the client
handleServerError(e) {
console.error("Action error:", e.message);
return "Something went wrong";
},
// Define a metadata schema (makes metadata type-safe)
defineMetadataSchema() {
return z.object({
actionName: z.string(),
});
},
// Change the default validation error shape
defaultValidationErrorsShape: "flattened",
});
```
`handleServerError` controls what the client sees when an error is thrown in your server code. By default, it logs the error and returns a generic `"Something went wrong"` message, preventing sensitive error details from leaking to the client.
## The immutability pattern [#the-immutability-pattern]
Every chainable method returns a **new client instance**, the original is never modified. This is the key design principle that enables client hierarchies:
```ts
// This doesn't modify actionClient, it returns a new instance
const authClient = actionClient.use(authMiddleware);
// actionClient still has no middleware
// authClient has authMiddleware
```
This means you can safely build on top of any client without worrying about side effects.
## Client hierarchy [#client-hierarchy]
In real applications, you typically create a tree of clients with increasingly specific middleware:
```ts title="src/lib/safe-action.ts"
import { createSafeActionClient } from "next-safe-action";
// Base client: error handling, logging, metadata
export const actionClient = createSafeActionClient({
handleServerError(e) {
console.error("Action error:", e.message);
return e.message;
},
});
// Authenticated client: requires valid session
export const authClient = actionClient.use(async ({ next }) => {
const session = await getSession();
if (!session) throw new Error("Unauthorized");
return next({ ctx: { user: session.user } });
});
// Admin client: requires admin role
export const adminClient = authClient.use(async ({ next, ctx }) => {
// ctx.user is available here (typed!) from the auth middleware
if (ctx.user.role !== "admin") throw new Error("Forbidden");
return next({ ctx: { isAdmin: true } });
});
```
Then use the appropriate client for each action:
```ts title="src/app/actions.ts"
"use server";
// Public action: no auth needed
export const getPublicData = actionClient
.action(async () => { /* ... */ });
// Authenticated action: user must be logged in
export const updateProfile = authClient
.inputSchema(profileSchema)
.action(async ({ parsedInput, ctx }) => {
// ctx.user is typed and available
});
// Admin action: user must be admin
export const deleteUser = adminClient
.inputSchema(z.object({ userId: z.string() }))
.action(async ({ parsedInput, ctx }) => {
// ctx.user and ctx.isAdmin are both available
});
```
## Chainable methods [#chainable-methods]
The client provides these methods, each returning a new instance:
| Method | Purpose |
| --------------------------- | --------------------------------------------------------------------------------------- |
| `.use(middleware)` | Add a pre-validation middleware function |
| `.metadata(data)` | Set action metadata (requires `defineMetadataSchema` in client options) |
| `.inputSchema(schema)` | Define input validation schema |
| `.useValidated(middleware)` | Add a post-validation middleware function (requires `inputSchema` or `bindArgsSchemas`) |
| `.outputSchema(schema)` | Define output validation schema |
| `.bindArgsSchemas(schemas)` | Define schemas for bound arguments |
| `.action(serverCode)` | Define the action (returns a callable function) |
| `.stateAction(serverCode)` | Define a stateful action (for React's `useActionState`) |
`.useValidated()` is only available after `.inputSchema()` or `.bindArgsSchemas()`. It adds middleware that runs after input validation with access to typed `parsedInput`. See the [middleware guide](/docs/guides/middleware#validated-middleware) for details.
See the [API reference](/docs/api/safe-action-client) for detailed signatures and parameters.
## What's next? [#whats-next]
Learn how Standard Schema validation works with your actions.
Deep dive into writing and composing middleware functions.
# Action result (/docs/concepts/action-result)
Every safe action returns a **result object**, a structured response that tells you exactly what happened. It always has the same shape, making error handling predictable and type-safe.
## Result structure [#result-structure]
The result is a **discriminated union**. At most one of `data`, `validationErrors`, or `serverError` is populated, and TypeScript enforces this at the type level — checking one field narrows the others to `undefined`:
```ts
type SafeActionResult =
| { data?: undefined; serverError?: undefined; validationErrors?: undefined } // idle / framework navigation
| { data: Data; serverError?: undefined; validationErrors?: undefined } // success
| { data?: undefined; serverError: ServerError; validationErrors?: undefined } // server error
| { data?: undefined; serverError?: undefined; validationErrors: ShapedErrors }; // validation failure
```
The four branches correspond to these outcomes:
| Outcome | `data` | `validationErrors` | `serverError` |
| --------------------------- | ------- | ------------------ | ------------- |
| Success | Present | - | - |
| Validation failure | - | Present | - |
| Server error | - | - | Present |
| Idle / framework navigation | - | - | - |
Framework navigation/errors (like `redirect()` or `notFound()`) are a special case. They don't populate any of the three fields. On the server the error is re-thrown so Next.js can handle the navigation; on the client, the hook exposes the idle branch `{}` together with a `"hasNavigated"` status. See [Error Handling](/docs/concepts/error-handling) for details.
## `data` [#data]
When your server code completes successfully, `data` contains whatever you returned:
```ts
export const greetUser = actionClient
.inputSchema(z.object({ name: z.string() }))
.action(async ({ parsedInput }) => {
return { greeting: `Hello, ${parsedInput.name}!` };
});
// On the client:
const result = await greetUser({ name: "Alice" });
// result.data → { greeting: "Hello, Alice!" }
// Type: { greeting: string } | undefined
```
The `data` type is **inferred** from your server code's return type. If you define an `outputSchema`, the type comes from the schema instead.
If your server code doesn't return anything, `result.data` is typed as exactly `undefined` rather than `void | undefined`. The runtime never emits a separate `{ data: undefined }` for void-returning actions (it returns `{}`), and the types mirror that: the idle and void-success branches collapse into a single shape. Discriminate success for these actions by checking the absence of errors instead of truthy `data`.
## `validationErrors` [#validationerrors]
When the input doesn't match the schema, `validationErrors` contains the validation failures. Your server code **never runs** in this case:
```ts
export const createUser = actionClient
.inputSchema(z.object({
name: z.string().min(2),
email: z.string().email(),
}))
.action(async ({ parsedInput }) => {
// This code doesn't run if validation fails
});
// On the client (with invalid input):
const result = await createUser({ name: "", email: "bad" });
// result.validationErrors → {
// name: { _errors: ["String must contain at least 2 character(s)"] },
// email: { _errors: ["Invalid email"] }
// }
```
The shape of `validationErrors` depends on the configured error shape (formatted or flattened). See [Input Validation](/docs/concepts/input-validation) for details.
You can also **manually return** validation errors from your server code using `returnValidationErrors()`:
```ts
import { returnValidationErrors } from "next-safe-action";
export const createUser = actionClient
.inputSchema(z.object({ email: z.string().email() }))
.action(async ({ parsedInput }) => {
const exists = await db.user.findByEmail(parsedInput.email);
if (exists) {
// Return a validation error for the email field
return returnValidationErrors(inputSchema, {
email: { _errors: ["Email already taken"] },
});
}
return { id: "123" };
});
```
## `serverError` [#servererror]
When an unexpected error is thrown in your server code or middleware, `serverError` contains the error message:
```ts
export const riskyAction = actionClient
.action(async () => {
throw new Error("Database connection failed");
});
// On the client:
const result = await riskyAction();
// result.serverError → "Something went wrong" (default message)
```
By default, the actual error message is **not** sent to the client, only the generic `"Something went wrong"` string. This prevents sensitive information from leaking. Customize this with `handleServerError` in [client options](/docs/api/create-safe-action-client).
For **expected** business errors ("out of stock", "not found"), you can populate `serverError` with a typed value of your choice using [`returnServerError()`](/docs/concepts/error-handling#expected-server-errors-with-returnservererror), which bypasses `handleServerError` entirely.
## Reading the result [#reading-the-result]
A typical pattern for handling all cases:
```ts
const result = await myAction(input);
if (result.data) {
// TypeScript knows serverError and validationErrors are undefined here
console.log(result.data);
} else if (result.validationErrors) {
// TypeScript knows data and serverError are undefined here
console.log(result.validationErrors);
} else if (result.serverError) {
// TypeScript knows data and validationErrors are undefined here
console.log(result.serverError);
}
```
Destructuring works the same way — checking any one of the three variables narrows the other two:
```ts
const { data, serverError, validationErrors } = await myAction(input);
if (data) {
// serverError and validationErrors are `undefined`
}
if (serverError) {
// data and validationErrors are `undefined`
}
```
### In hooks [#in-hooks]
With the `useAction` hook (and `useOptimisticAction`, `useStateAction`), the return object is itself a **discriminated union keyed on `status`** and shorthand booleans. Checking any discriminant narrows `result` to the matching branch:
```ts
const action = useAction(myAction);
// Status-based narrowing
if (action.hasSucceeded) {
action.result.data; // Data (guaranteed)
action.result.serverError; // undefined
action.result.validationErrors; // undefined
}
if (action.hasErrored) {
action.result.data; // undefined
// Further narrow between error kinds:
if (action.result.serverError) { /* ... */ }
if (action.result.validationErrors) { /* ... */ }
}
```
Lifecycle callbacks also benefit from narrowing:
```ts
const { execute } = useAction(myAction, {
onSuccess: ({ data }) => { /* data is guaranteed here */ },
onError: ({ error }) => {
if (error.validationErrors) { /* ... */ }
if (error.serverError) { /* ... */ }
},
});
```
See the [Type narrowing](/docs/guides/hooks#type-narrowing) section for more patterns.
**Precedence for edge cases.** In rare situations where the runtime could otherwise produce multiple populated fields (e.g. invalid bind args combined with invalid main input, or middleware that throws after `await next()` has already received a validation-error result), next-safe-action applies a fixed precedence: `validationErrors` > `serverError` > `data`. The higher-priority state fully describes the outcome; lower-priority state is discarded. This keeps the discriminated union honest at runtime. See [Error precedence](/docs/concepts/error-handling#error-precedence) for the exact behavior, including how `handleServerError` and `throwServerError` interact with this rule.
If your action uses `bindArgsSchemas()`, validation errors for bound arguments appear in `validationErrors` as well. They're keyed by the argument position in the tuple:
```ts
export const updateItem = authClient
.bindArgsSchemas([z.string().uuid()])
.inputSchema(z.object({ name: z.string() }))
.action(async ({ parsedInput, bindArgsParsedInputs: [itemId] }) => {
// ...
});
// Bound with an invalid UUID:
const boundAction = updateItem.bind(null, "not-a-uuid");
const result = await boundAction({ name: "test" });
// result.validationErrors includes bind args errors
```
See [Bind Arguments](/docs/advanced/bind-arguments) for more details.
## What's next? [#whats-next]
Learn the full error taxonomy: validation, server, and framework errors.
Use useAction for reactive result handling with callbacks and status tracking.
# Error handling (/docs/concepts/error-handling)
next-safe-action has three categories of errors, each handled differently:
## Validation errors [#validation-errors]
Validation errors occur when the client sends data that doesn't match the input schema. They're **returned** in the result object (not thrown) and are always safe to show to the user:
```ts
const result = await createUser({ name: "", email: "bad" });
result.validationErrors;
// → { name: { _errors: ["Too short"] }, email: { _errors: ["Invalid email"] } }
```
Validation errors are produced in two ways:
1. **Automatically**: when Standard Schema validation fails on input or bind args
2. **Manually**: when you call `returnValidationErrors()` in your server code (e.g., "email already taken")
```ts
import { returnValidationErrors } from "next-safe-action";
export const signUp = actionClient
.inputSchema(schema)
.action(async ({ parsedInput }) => {
const exists = await db.user.findByEmail(parsedInput.email);
if (exists) {
return returnValidationErrors(schema, {
email: { _errors: ["Already registered"] },
});
}
// ...
});
```
`returnValidationErrors` actually **throws** internally (it never returns), which ensures the remaining server code doesn't execute.
See [Input Validation](/docs/concepts/input-validation) for error shapes and [Custom Validation Errors](/docs/advanced/custom-validation-errors) for advanced formatting.
## Server errors [#server-errors]
Server errors are **unexpected failures**, such as database timeouts, API failures, or bugs in your server code. By default, next-safe-action:
1. Catches the thrown error
2. Passes it to `handleServerError` (which you define in client options)
3. Returns the handler's return value as `result.serverError`
```ts
const actionClient = createSafeActionClient({
handleServerError(e) {
// This runs when any action throws an unexpected error
console.error("Action error:", e.message);
// What you return here becomes result.serverError on the client
// Default: "Something went wrong"
return e.message;
},
});
```
**Security**: The default `handleServerError` returns a generic `"Something went wrong"` message. If you return `e.message`, make sure your errors don't contain sensitive information (stack traces, database queries, etc.).
### Expected server errors with `returnServerError` [#expected-server-errors-with-returnservererror]
Not every server error is unexpected. For known business failures ("out of stock", "not found", "quota exceeded"), you can return a typed server error to the client with `returnServerError()`. The value is set as `result.serverError` as-is, **bypassing `handleServerError`**:
```ts
import { returnServerError } from "next-safe-action";
export const buyProduct = actionClient
.inputSchema(schema)
.action(async ({ parsedInput }) => {
const product = await db.product.find(parsedInput.id);
if (!product.inStock) {
returnServerError({ code: "OUT_OF_STOCK", message: "This product is sold out" });
}
// ...
});
```
A few things to keep in mind:
* Like `returnValidationErrors`, it **throws** internally (it never returns), so the remaining server code doesn't execute. It also works from middleware.
* The value should conform to the client's `ServerError` type, which is inferred from `handleServerError`'s return type. See [Typing the error payload](#typing-the-error-payload) below.
* The value must be **JSON-serializable** (no circular references, BigInts, functions, etc.), since it crosses the server/client boundary. This also makes it work inside `"use cache"` scopes when `cacheComponents` is enabled. Non-serializable payloads fail loudly with a `TypeError` on the server (handled by `handleServerError` like any unexpected error), instead of silently degrading.
#### Typing the error payload [#typing-the-error-payload]
`returnServerError` is generic (`returnServerError(serverError: SE): never`) and `SE` is inferred from the argument, so there's no automatic type-level link between the payload you pass and the client's `ServerError` type. Strictness is opt-in, via three complementary techniques.
**1. Declare the error union on `handleServerError`.** The client's `ServerError` type is inferred from `handleServerError`'s return type, so this is what types `result.serverError` on the client:
```ts
type AppServerError =
| { code: "INTERNAL"; message: string }
| { code: "OUT_OF_STOCK"; message: string }
| { code: "NOT_FOUND"; message: string };
const actionClient = createSafeActionClient({
handleServerError: (e): AppServerError => ({ code: "INTERNAL", message: e.message }),
});
```
On the client, `result.serverError` is now `AppServerError | undefined`, and `if (serverError?.code === "OUT_OF_STOCK")` narrows as a normal discriminated union.
**2. Enforce the payload at the call site.** Either pass the generic explicitly, or use `satisfies`:
```ts
returnServerError({ code: "OUT_OF_STOCK", message: "This product is sold out" });
// or
returnServerError({ code: "OUT_OF_STOCK", message: "This product is sold out" } satisfies AppServerError);
```
Both make typos in `code` or missing fields a compile error.
**3. Recommended: export a typed alias next to your action client.** One line gives every call site full checking with zero annotation noise:
```ts title="lib/safe-action.ts"
export const returnAppError: (e: AppServerError) => never = returnServerError;
```
Without one of these techniques, `returnServerError({ anything: true })` compiles even though `result.serverError` claims to be the client's `ServerError` type. This is an inherent limit of a standalone helper: prefer the typed alias (technique 3) as your app's default pattern.
### Throwing errors instead of returning them [#throwing-errors-instead-of-returning-them]
By default, validation and server errors are **returned** in the result object. You can opt into **throwing** them instead using boolean flags, which is useful when you want errors to propagate to an error boundary or a try/catch block.
**`throwServerError`**: action-level only. When enabled, server errors are re-thrown instead of being returned in `result.serverError`:
```ts
export const myAction = actionClient
.inputSchema(schema)
.action(
async ({ parsedInput }) => {
// ...
},
{
throwServerError: true,
}
);
```
**`throwValidationErrors`**: available at both client and action level. When set at both levels, the action-level setting takes priority:
```ts
// Client-level: applies to all actions created from this client
const actionClient = createSafeActionClient({
throwValidationErrors: true,
});
// Action-level: overrides the client setting for this specific action
export const myAction = actionClient
.inputSchema(schema)
.action(
async ({ parsedInput }) => {
// ...
},
{
throwValidationErrors: true,
}
);
```
These flags control whether the **final** error is returned in the result object or thrown. They don't replace `handleServerError` (which still processes server errors before the throw/return decision) or `returnValidationErrors()` (which is a function for manually producing validation errors in your server code).
## Framework navigation/errors [#framework-navigationerrors]
Framework navigation/errors are **navigation events** triggered by Next.js functions like `redirect()`, `notFound()`, `forbidden()`, and `unauthorized()`. These are special because they're not really "errors", but control flow mechanisms that Next.js uses to trigger navigation.
next-safe-action detects and handles these automatically:
```ts
import { redirect } from "next/navigation";
export const loginAction = actionClient
.inputSchema(loginSchema)
.action(async ({ parsedInput }) => {
const user = await authenticate(parsedInput);
// This triggers a redirect, not a normal return
redirect("/dashboard");
});
```
### What happens with framework errors [#what-happens-with-framework-errors]
1. **On the server**: The error is caught, identified as a framework error, and re-thrown so Next.js can handle the navigation
2. **On the client**: If using `useAction`, the hook detects the navigation and sets `status` to `"hasNavigated"` (instead of `"hasSucceeded"` or `"hasErrored"`)
3. **Callbacks**: The `onNavigation` callback fires (instead of `onSuccess` or `onError`)
### Navigation kinds [#navigation-kinds]
The `navigationKind` property tells you what type of navigation occurred:
| Function | `navigationKind` |
| ---------------- | ---------------- |
| `redirect()` | `"redirect"` |
| `notFound()` | `"notFound"` |
| `forbidden()` | `"forbidden"` |
| `unauthorized()` | `"unauthorized"` |
```ts
const { execute } = useAction(myAction, {
onNavigation: ({ navigationKind }) => {
if (navigationKind === "redirect") {
// Action triggered a redirect
}
},
});
```
See [Framework Errors](/docs/advanced/framework-errors) for advanced configuration.
## Error precedence [#error-precedence]
The action result is a discriminated union: at most one of `data`, `serverError`, and `validationErrors` is populated at a time. In most executions only one field is ever set, but a few compound scenarios can reach the final result-building step with multiple candidates:
* Invalid bind args (wrapped as a server error) combined with invalid main input (validation errors).
* Middleware that calls `await next()`, receives a result that already contains `validationErrors`, then throws afterwards (for example, a post-validation audit/cleanup step that fails).
In these cases next-safe-action applies a fixed precedence when assembling the returned result:
```
validationErrors > serverError > data
```
The winning field fully describes the outcome; the lower-priority field is dropped from the returned object. For the example above where middleware throws after receiving validation errors, the client receives only the validation errors, and the thrown server-side error is not present in the result.
### What still runs for dropped server errors [#what-still-runs-for-dropped-server-errors]
The precedence rule only affects what appears in the **returned result**, not whether `handleServerError` executes:
1. When middleware or server code throws, `handleServerError` is invoked immediately with the thrown error, regardless of any pre-existing `validationErrors`.
2. Only after `handleServerError` has run does the result-building step apply precedence and decide which field to keep.
This means logging, telemetry, Sentry integrations, and any other side effects you configure inside `handleServerError` always fire for thrown errors, even when the eventual result carries `validationErrors` instead of `serverError`. Treat `handleServerError` as the authoritative place for server-side observability; the returned result is the client-facing summary, not a full event log.
### Interaction with `throwServerError` [#interaction-with-throwservererror]
The `throwServerError` action-level flag is only consulted when no `validationErrors` are present. If the compound case produces both, the validation errors take precedence and `throwServerError` does not fire:
```ts
export const myAction = actionClient
.inputSchema(schema)
.use(async ({ next }) => {
const result = await next();
if (result.validationErrors) {
// This throw is caught, passed to `handleServerError`,
// and its return value is assigned to `middlewareResult.serverError`
// but the returned result still surfaces `validationErrors`.
throw new Error("audit cleanup failed");
}
return result;
})
.action(
async () => {
// ...
},
{ throwServerError: true } // NOT re-thrown in the compound case above
);
```
If you need to guarantee that an operational failure propagates even in compound cases, raise it from `handleServerError` yourself (for example by logging and then rethrowing in paths you want to hard-fail), or gate the post-`next()` side effects on `result.validationErrors === undefined` so they don't run when validation has already failed.
## Error handling summary [#error-handling-summary]
| Error type | How it's produced | Where it appears | Safe for users? |
| ------------------- | -------------------------------------------------- | ------------------------- | ------------------------------ |
| Validation | Schema parse failure or `returnValidationErrors()` | `result.validationErrors` | Yes |
| Server (unexpected) | Thrown error in server code/middleware | `result.serverError` | Depends on `handleServerError` |
| Server (expected) | `returnServerError()` | `result.serverError` | Yes (you control the value) |
| Framework | `redirect()`, `notFound()`, etc. | Navigation occurs | N/A (handled by Next.js) |
## What's next? [#whats-next]
Customize error shapes, flatten errors, and manually return validation errors.
Advanced configuration for redirect, notFound, forbidden, and unauthorized.
# How it works (/docs/concepts/how-it-works)
## The action lifecycle [#the-action-lifecycle]
When you call a safe action, it goes through a well-defined pipeline on the server before returning a result to the client:
1. **Client Call**: the action function is called from a Client Component (directly, via `useAction`, or via a form)
2. **Middleware**: the `use()` middleware stack runs in order, each layer can short-circuit or extend the context
3. **Validate Input**: the raw client input is parsed and validated against the input schema via [Standard Schema](https://github.com/standard-schema/standard-schema)
4. **Validated Middleware**: if validation succeeded, the `useValidated()` middleware stack runs with typed `parsedInput` and accumulated `ctx`. Skipped entirely if validation fails.
5. **Server Code**: your async function runs with the validated `parsedInput` and accumulated `ctx`
6. **Validate Output**: if an `outputSchema` is defined, the return value is validated before being sent to the client
If any step fails, the pipeline stops and returns an appropriate error in the [action result](/docs/concepts/action-result).
## Server vs client [#server-vs-client]
next-safe-action has three entry points, each designed for a specific environment:
| Entry point | Environment | Purpose |
| --------------------------------- | ----------- | ---------------------------------------------------------------------------------- |
| `next-safe-action` | Server only | Define actions with `createSafeActionClient`, middleware, validation |
| `next-safe-action/hooks` | Client only | `useAction`, `useOptimisticAction`, and `useStateAction` hooks |
| `next-safe-action/stateful-hooks` | Client only | Re-exports `useStateAction` from `next-safe-action/hooks` (backward compatibility) |
Server code (your action function) **never runs on the client**. Next.js ensures this by replacing the server function with a network call when the `"use server"` directive is present.
## The middleware pipeline [#the-middleware-pipeline]
Middleware functions wrap your server code like layers of an onion. Each middleware can run code **before** calling `next()`, and **after** the inner layers complete:
```ts title="Example: Two middleware layers"
const actionClient = createSafeActionClient()
// Layer 1: Logging
.use(async ({ next }) => {
const start = Date.now();
const result = await next();
console.log(`Action took ${Date.now() - start}ms`);
return result;
})
// Layer 2: Auth
.use(async ({ next }) => {
const session = await getSession();
if (!session) throw new Error("Unauthorized");
return next({ ctx: { user: session.user } });
});
```
Key concepts:
* **`next()`** calls the next layer (or the server code if there are no more middleware)
* **`ctx`** (context) accumulates through the chain, each middleware can add to it via `next({ ctx: { ... } })`
* **Short-circuiting**: throwing an error in middleware stops the pipeline and returns a server error
* The returned result flows **outward** through each middleware, so logging middleware can measure total time
Learn more in the [Middleware guide](/docs/guides/middleware).
Most middleware should use `use()`, which covers authentication, logging, rate limiting, and context enrichment. If you specifically need middleware that runs **after** input validation with access to typed `parsedInput`, see [validated middleware](/docs/guides/middleware#validated-middleware) (the `useValidated()` method).
## How actions are defined [#how-actions-are-defined]
Every action starts from a **safe action client**, a builder object that accumulates configuration:
```ts
const myAction = actionClient // 1. Start from client
.use(authMiddleware) // 2. Add middleware (optional)
.metadata({ role: "admin" }) // 3. Set metadata (optional)
.inputSchema(z.object({ id: z.string() })) // 4. Define input
.useValidated(logParsedInput) // 5. Validated middleware (optional)
.outputSchema(z.object({ ok: z.boolean() })) // 6. Define output (optional)
.action(async ({ parsedInput, ctx }) => { // 7. Server code
return { ok: true };
});
```
Each method returns a **new immutable client instance**, the original is never modified. This lets you build a hierarchy of increasingly specialized clients. See [Action Client](/docs/concepts/action-client) for more.
## What's next? [#whats-next]
Learn how to create and configure the safe action client.
Understand how Standard Schema validation works with your actions.
# Input validation (/docs/concepts/input-validation)
Input validation is the core feature of next-safe-action. Every action can define an input schema that validates and types the data before your server code runs. This uses the [Standard Schema](https://github.com/standard-schema/standard-schema) specification, so you can use **any** compatible validation library.
## Defining an input schema [#defining-an-input-schema]
Use the `.inputSchema()` method to attach a schema to your action:
```ts title="src/app/actions.ts"
"use server";
import { z } from "zod";
import { actionClient } from "@/lib/safe-action";
export const createUser = actionClient
.inputSchema(z.object({
name: z.string().min(2),
email: z.string().email(),
age: z.number().min(18).optional(),
}))
.action(async ({ parsedInput }) => {
// parsedInput is typed as { name: string; email: string; age?: number }
return { id: "123", ...parsedInput };
});
```
```ts title="src/app/actions.ts"
"use server";
import * as v from "valibot";
import { actionClient } from "@/lib/safe-action";
export const createUser = actionClient
.inputSchema(v.object({
name: v.pipe(v.string(), v.minLength(2)),
email: v.pipe(v.string(), v.email()),
age: v.optional(v.pipe(v.number(), v.minValue(18))),
}))
.action(async ({ parsedInput }) => {
// parsedInput is typed as { name: string; email: string; age?: number }
return { id: "123", ...parsedInput };
});
```
The `parsedInput` parameter in your server code is **fully typed** based on the schema's output type. TypeScript will error if you access a property that doesn't exist.
## How validation works [#how-validation-works]
When an action is called, the input goes through this flow:
1. **Client sends raw input**: the unvalidated data from the client
2. **Standard Schema parse**: the input is validated against your schema
3. **Success** → your server code receives `parsedInput` (typed and validated)
4. **Failure** → the action returns `validationErrors` immediately (your server code never runs)
The raw `clientInput` is also available in middleware and server code if you need access to the original, unvalidated data.
### After validation: validated middleware [#after-validation-validated-middleware]
If you need to run middleware that has access to the validated, typed `parsedInput` (for example, authorization checks that depend on the input), use `useValidated()` instead of `use()`. Validated middleware runs immediately after successful input validation and before your server code:
```ts title="src/app/actions.ts"
authClient
.inputSchema(z.object({ postId: z.string() }))
.useValidated(async ({ parsedInput, ctx, next }) => {
// parsedInput.postId is typed as string
const post = await db.post.findUnique({ where: { id: parsedInput.postId } });
if (!post || post.authorId !== ctx.user.id) throw new Error("Forbidden");
return next({ ctx: { post } });
})
.action(async ({ ctx }) => {
// ctx.post is typed and available
});
```
If validation fails, validated middleware is completely skipped. See the [middleware guide](/docs/guides/middleware#validated-middleware) for more.
## Validation error shapes [#validation-error-shapes]
When validation fails, the error object structure depends on the configured shape. There are two built-in shapes:
### Formatted (default) [#formatted-default]
The default shape mirrors your schema structure with `_errors` arrays at each level:
```ts
// Schema: z.object({ name: z.string().min(2), email: z.string().email() })
// Input: { name: "", email: "invalid" }
{
validationErrors: {
name: { _errors: ["String must contain at least 2 character(s)"] },
email: { _errors: ["Invalid email"] },
}
}
```
### Flattened [#flattened]
The flattened shape separates form-level errors from field-level errors:
```ts
// Same schema and input as above
{
validationErrors: {
formErrors: [],
fieldErrors: {
name: ["String must contain at least 2 character(s)"],
email: ["Invalid email"],
},
}
}
```
You can set the default shape when creating the client:
```ts
const actionClient = createSafeActionClient({
defaultValidationErrorsShape: "flattened",
});
```
Or override it per-action. See [Custom Validation Errors](/docs/advanced/custom-validation-errors) for details.
## Supported libraries [#supported-libraries]
Any library that implements the [Standard Schema](https://github.com/standard-schema/standard-schema) specification works with next-safe-action. This includes:
| Library | Status |
| ------------------------------- | --------------- |
| [Zod](https://zod.dev/) | Fully supported |
| [Valibot](https://valibot.dev/) | Fully supported |
| [ArkType](https://arktype.io/) | Fully supported |
See the [Standard Schema integration guide](/docs/integrations/standard-schema) for side-by-side comparisons.
## What's next? [#whats-next]
Learn the full structure of the result object returned by actions.
Customize error shapes, format errors, and manually return validation errors.
# createMiddleware() (/docs/api/create-middleware)
`createMiddleware` creates a standalone middleware function that can be shared across multiple action clients. It provides type constraints so TypeScript can verify the middleware is only used with compatible clients.
```ts
import { createMiddleware } from "next-safe-action";
const myMiddleware = createMiddleware().define(middlewareFn);
```
## Signature [#signature]
```ts
function createMiddleware<
BaseData extends {
serverError?: any;
ctx?: object;
metadata?: any;
}
>(): {
define: (middlewareFn: MiddlewareFn) => MiddlewareFn;
};
```
## Generic parameter [#generic-parameter]
`createMiddleware` accepts a single generic parameter `BaseData` that declares the **minimum** requirements for the middleware. The client using this middleware must have at least these properties available.
## `.define()` method [#define-method]
The `define` method accepts a middleware function and returns it with proper typing. The middleware function receives the same options as inline `.use()` middleware:
## Examples [#examples]
### No constraints (universal middleware) [#no-constraints-universal-middleware]
```ts title="src/lib/middleware/logging.ts"
import { createMiddleware } from "next-safe-action";
export const loggingMiddleware = createMiddleware().define(
async ({ next, metadata }) => {
const start = Date.now();
const result = await next();
console.log(`Action took ${Date.now() - start}ms`, metadata);
return result;
}
);
```
### With context constraints [#with-context-constraints]
```ts title="src/lib/middleware/admin-guard.ts"
import { createMiddleware } from "next-safe-action";
// Requires ctx.user with a role property
export const adminGuard = createMiddleware<{
ctx: { user: { id: string; role: string } };
}>().define(async ({ next, ctx }) => {
if (ctx.user.role !== "admin") {
throw new Error("Admin access required");
}
// ctx.user is fully typed here
return next();
});
```
### With metadata constraints [#with-metadata-constraints]
```ts title="src/lib/middleware/rate-limit.ts"
import { createMiddleware } from "next-safe-action";
export const rateLimitMiddleware = createMiddleware<{
metadata: { actionName: string };
}>().define(async ({ next, metadata }) => {
await checkRateLimit(metadata.actionName);
return next();
});
```
### Extending context [#extending-context]
```ts title="src/lib/middleware/with-db.ts"
import { createMiddleware } from "next-safe-action";
export const withDb = createMiddleware().define(async ({ next }) => {
const db = await getDbConnection();
return next({
ctx: { db }, // Adds db to context for downstream middleware/actions
});
});
```
## Usage with clients [#usage-with-clients]
```ts title="src/lib/safe-action.ts"
import { createSafeActionClient } from "next-safe-action";
import { loggingMiddleware } from "./middleware/logging";
import { adminGuard } from "./middleware/admin-guard";
const baseClient = createSafeActionClient().use(loggingMiddleware);
// ✅ Works: adminGuard requires ctx.user, which authMiddleware provides
const adminClient = baseClient
.use(async ({ next }) => {
const user = await getUser();
return next({ ctx: { user } });
})
.use(adminGuard);
// ❌ Type error: adminGuard requires ctx.user, but baseClient doesn't have it
const broken = baseClient.use(adminGuard);
```
## See also [#see-also]
* [Middleware guide](/docs/guides/middleware): foundational middleware concepts
* [Standalone middleware](/docs/advanced/standalone-middleware): guide with more patterns and use cases
* [`.use()` method](/docs/api/safe-action-client#use): how standalone middleware is consumed by clients
* [`createValidatedMiddleware()`](/docs/api/create-validated-middleware): standalone factory for post-validation middleware
# createSafeActionClient() (/docs/api/create-safe-action-client)
`createSafeActionClient` creates a new safe action client instance. This is the entry point for defining type-safe server actions.
```ts
import { createSafeActionClient } from "next-safe-action";
const actionClient = createSafeActionClient(opts);
```
## Parameters [#parameters]
`createSafeActionClient` accepts an optional options object:
## Return value [#return-value]
Returns a [`SafeActionClient`](/docs/api/safe-action-client) instance with all chainable methods available.
## Examples [#examples]
### Minimal client [#minimal-client]
```ts title="src/lib/safe-action.ts"
import { createSafeActionClient } from "next-safe-action";
export const actionClient = createSafeActionClient();
```
### Custom error handling [#custom-error-handling]
```ts title="src/lib/safe-action.ts"
import { createSafeActionClient } from "next-safe-action";
export const actionClient = createSafeActionClient({
handleServerError: (error, { metadata }) => {
// Log to your error tracking service
reportError(error, { metadata });
// Return a user-friendly message
if (error instanceof DatabaseError) {
return "A database error occurred. Please try again.";
}
return "Something went wrong.";
},
});
```
### With metadata schema [#with-metadata-schema]
```ts title="src/lib/safe-action.ts"
import { createSafeActionClient } from "next-safe-action";
import { z } from "zod";
export const actionClient = createSafeActionClient({
defineMetadataSchema: () =>
z.object({
actionName: z.string(),
}),
});
// All actions using this client must now call .metadata()
export const myAction = actionClient
.metadata({ actionName: "myAction" })
.action(async () => {
// ...
});
```
### Flattened validation errors [#flattened-validation-errors]
```ts title="src/lib/safe-action.ts"
import { createSafeActionClient } from "next-safe-action";
export const actionClient = createSafeActionClient({
defaultValidationErrorsShape: "flattened",
});
// All actions using this client return flattened errors:
// { formErrors: string[], fieldErrors: { [field]: string[] } }
```
## `ServerErrorFunctionUtils` [#servererrorfunctionutils]
The second argument passed to `handleServerError`:
## See also [#see-also]
* [Action client](/docs/concepts/action-client): conceptual overview of the client pattern
* [SafeActionClient methods](/docs/api/safe-action-client): all chainable methods available on the returned client
* [Metadata](/docs/advanced/metadata): using `defineMetadataSchema` for type-safe action metadata
* [Error handling](/docs/concepts/error-handling): understanding `handleServerError` in context
# createValidatedMiddleware() (/docs/api/create-validated-middleware)
`createValidatedMiddleware` creates a standalone validated middleware function for use with `.useValidated()`. It works the same way as `createMiddleware()`, but the middleware function also receives typed `parsedInput`, `clientInput`, `bindArgsParsedInputs`, and `bindArgsClientInputs`.
```ts
import { createValidatedMiddleware } from "next-safe-action";
const myMiddleware = createValidatedMiddleware().define(middlewareFn);
```
Most middleware should use [`createMiddleware()`](/docs/api/create-middleware) with `.use()` instead. Only use `createValidatedMiddleware()` when the middleware specifically needs access to the validated `parsedInput`, for example to check resource ownership or log transformed input. See [when to use `useValidated()` vs `use()`](/docs/guides/middleware#when-to-use-usevalidated-vs-use) for guidance.
## Signature [#signature]
```ts
function createValidatedMiddleware<
BaseData extends {
serverError?: any;
ctx?: object;
metadata?: any;
parsedInput?: unknown;
clientInput?: unknown;
bindArgsParsedInputs?: readonly unknown[];
bindArgsClientInputs?: readonly unknown[];
}
>(): {
define: (middlewareFn: ValidatedMiddlewareFn) => ValidatedMiddlewareFn;
};
```
## Generic parameter [#generic-parameter]
`createValidatedMiddleware` accepts a single generic parameter `BaseData` with all the properties from `createMiddleware`, plus input-related constraints:
## `.define()` method [#define-method]
The `define` method accepts a validated middleware function. The function receives all the properties from inline `useValidated()` middleware: `parsedInput`, `clientInput`, `bindArgsParsedInputs`, `bindArgsClientInputs`, `ctx`, `metadata`, and `next`.
## Examples [#examples]
### With parsedInput constraint [#with-parsedinput-constraint]
```ts title="src/lib/middleware/log-user.ts"
import { createValidatedMiddleware } from "next-safe-action";
export const logUserMiddleware = createValidatedMiddleware<{
parsedInput: { userId: string };
}>().define(async ({ parsedInput, next }) => {
console.log("Acting on user:", parsedInput.userId);
return next();
});
```
### With context and parsedInput constraints [#with-context-and-parsedinput-constraints]
```ts title="src/lib/middleware/ownership-check.ts"
import { createValidatedMiddleware } from "next-safe-action";
export const ownershipCheck = createValidatedMiddleware<{
ctx: { user: { id: string } };
parsedInput: { resourceId: string };
}>().define(async ({ parsedInput, ctx, next }) => {
const resource = await db.resource.findUnique({
where: { id: parsedInput.resourceId },
});
if (resource?.ownerId !== ctx.user.id) {
throw new Error("Forbidden");
}
return next({ ctx: { resource } });
});
```
### Usage with clients [#usage-with-clients]
```ts title="src/lib/safe-action.ts"
import { ownershipCheck } from "./middleware/ownership-check";
const ownerAction = authClient
.inputSchema(z.object({ resourceId: z.string() }))
.useValidated(ownershipCheck);
// ✅ Works: ownershipCheck requires ctx.user (from auth) and parsedInput.resourceId
// ❌ Type error if used without auth middleware or without resourceId in schema
```
## See also [#see-also]
* [Validated middleware guide](/docs/guides/middleware#validated-middleware): practical patterns for `useValidated()`
* [Standalone middleware](/docs/advanced/standalone-middleware): guide with reuse patterns
* [`.useValidated()` method](/docs/api/safe-action-client#usevalidated): how standalone validated middleware is consumed
* [`createMiddleware()`](/docs/api/create-middleware): standalone pre-validation middleware factory
# Error classes (/docs/api/error-classes)
next-safe-action exports several error classes that are thrown during action execution. You can use these in `handleServerError` or `try/catch` blocks to identify specific error types.
All error classes are imported from the main entry point:
```ts
import {
ActionValidationError,
ActionBindArgsValidationError,
ActionMetadataValidationError,
ActionOutputDataValidationError,
} from "next-safe-action";
```
## `ActionValidationError` [#actionvalidationerror]
Thrown when input validation fails **and** `throwValidationErrors` is enabled (either at the client level or per action). Contains the shaped validation errors (after `handleValidationErrorsShape` is applied).
```ts
class ActionValidationError extends Error {
validationErrors: ShapedErrors;
}
```
```ts
// Enable throwing per action
export const myAction = actionClient.action(
async ({ parsedInput }, { throwValidationErrors }) => {
throwValidationErrors(schema, {
email: { _errors: ["Already registered"] },
});
}
);
// Or enable globally
const actionClient = createSafeActionClient({
throwValidationErrors: true,
});
// Catch in handleServerError
const actionClient = createSafeActionClient({
throwValidationErrors: true,
handleServerError: (error) => {
if (error instanceof ActionValidationError) {
// error.validationErrors is available
return "Validation failed";
}
return DEFAULT_SERVER_ERROR_MESSAGE;
},
});
```
***
## `ActionBindArgsValidationError` [#actionbindargsvalidationerror]
Thrown internally when bind argument validation fails. This error is caught by the action builder and the validation errors are returned in the result.
```ts
class ActionBindArgsValidationError extends Error {
validationErrors: unknown[];
}
```
This error is handled internally by the action builder. You typically don't need to catch it yourself unless you're building custom error handling in `handleServerError`.
***
## `ActionMetadataValidationError` [#actionmetadatavalidationerror]
Thrown when the metadata provided via `.metadata()` doesn't match the schema defined by `defineMetadataSchema`. This is a developer error, meaning the metadata value doesn't conform to the schema.
```ts
class ActionMetadataValidationError extends Error {
validationErrors: ValidationErrors;
}
```
***
## `ActionOutputDataValidationError` [#actionoutputdatavalidationerror]
Thrown when the action's return value doesn't match the schema defined by `.outputSchema()`. This is a developer error, meaning the server code is returning data that doesn't conform to the output schema.
```ts
class ActionOutputDataValidationError extends Error {
validationErrors: ValidationErrors;
}
```
***
## Error handling patterns [#error-handling-patterns]
### Identifying errors in `handleServerError` [#identifying-errors-in-handleservererror]
```ts
import {
ActionValidationError,
ActionMetadataValidationError,
ActionOutputDataValidationError,
} from "next-safe-action";
const actionClient = createSafeActionClient({
throwValidationErrors: true,
handleServerError: (error) => {
if (error instanceof ActionValidationError) {
return "Please check your input.";
}
if (error instanceof ActionMetadataValidationError) {
console.error("Developer error: invalid metadata", error.validationErrors);
return "Internal error";
}
if (error instanceof ActionOutputDataValidationError) {
console.error("Developer error: invalid output", error.validationErrors);
return "Internal error";
}
return "Something went wrong.";
},
});
```
## See also [#see-also]
* [Error handling](/docs/concepts/error-handling): the complete error taxonomy
* [Custom validation errors](/docs/advanced/custom-validation-errors): customizing error shapes and manual error returns
* [Validation utilities](/docs/api/validation-utilities): `returnValidationErrors` and formatting functions
* [`createSafeActionClient()`](/docs/api/create-safe-action-client): `handleServerError` and `throwValidationErrors` options
# Hooks API (/docs/api/hooks-api)
next-safe-action provides React hooks for executing server actions from client components. All hooks are imported from `next-safe-action/hooks`.
## `useAction` [#useaction]
The primary hook for executing server actions from client components.
```ts
import { useAction } from "next-safe-action/hooks";
const { execute, result, status, ... } = useAction(safeActionFn, callbacks?);
```
### Parameters [#parameters]
`opts.initResult` sets the initial result before the first execution (defaults to `{}`), useful for preloading the hook with data fetched on the server. It is captured once at mount, like React's `useActionState` initial state: later changes to the option are ignored, and `reset()` restores the mount value.
### Return object [#return-object]
The return object is a **discriminated union** keyed on `status` and the shorthand booleans (`hasSucceeded`, `hasErrored`, etc.). Checking any discriminant narrows the `result` type. For example, when `hasSucceeded` is `true`, `result.data` is guaranteed to be `Data` (not `Data | undefined`), and `result.serverError` / `result.validationErrors` are narrowed to `undefined`. See the [Type narrowing](/docs/guides/hooks#type-narrowing) guide for details.
### Example [#example]
```tsx
"use client";
import { useAction } from "next-safe-action/hooks";
import { createUser } from "./actions";
export function CreateUserForm() {
const { execute, result, isPending, hasSucceeded, hasErrored } = useAction(createUser, {
onSuccess: ({ data }) => {
console.log("Created user:", data.id);
},
onError: ({ error }) => {
console.error("Failed:", error.serverError);
},
});
return (
);
}
```
***
## `useOptimisticAction` [#useoptimisticaction]
Execute actions with optimistic UI updates. The state updates immediately on execute and reverts if the action fails.
```ts
import { useOptimisticAction } from "next-safe-action/hooks";
const { execute, optimisticState, ... } = useOptimisticAction(safeActionFn, utils);
```
### Parameters [#parameters-1]
The `utils` object also accepts all [HookBaseOptions](#hookbaseoptions) properties including `throwOnNavigation` and lifecycle callbacks. When `throwOnNavigation` is `true`, `onNavigation` and `onSettled` are not available.
### Return object [#return-object-1]
Same as [`useAction`](#return-object) plus:
### Example [#example-1]
```tsx
"use client";
import { useOptimisticAction } from "next-safe-action/hooks";
import { toggleTodo } from "./actions";
export function TodoItem({ todo }: { todo: Todo }) {
const { execute, optimisticState } = useOptimisticAction(toggleTodo, {
currentState: todo,
updateFn: (state, input) => ({
...state,
completed: !state.completed,
}),
});
return (
);
}
```
***
## `useStateAction` [#usestateaction]
Execute stateful actions (defined with `.stateAction()`) with full lifecycle control and `
);
}
```
***
## `HookBaseOptions` [#hookbaseoptions]
Configuration and lifecycle callbacks for `useAction`, `useOptimisticAction`, and `useStateAction`. The available callbacks depend on the `throwOnNavigation` value:
When `throwOnNavigation` is `true`, TypeScript prevents you from passing `onNavigation` or `onSettled` callbacks. This is because the render-phase throw prevents React from committing effects, so these callbacks can never execute. See [why callbacks can't fire](/docs/advanced/framework-errors#why-callbacks-cant-fire-with-throwonnavigation-true) for details.
***
## `HookCallbacks` [#hookcallbacks]
Lifecycle callbacks shared by all hooks:
***
## `HookActionStatus` [#hookactionstatus]
Union type representing all possible hook states:
```ts
type HookActionStatus =
| "idle" // No action executed yet (or after reset)
| "executing" // Action is running on the server
| "hasSucceeded" // Action completed with data, no errors
| "hasErrored" // Action completed with errors
| "hasNavigated"; // Navigation function was called
```
***
## `HookShorthandStatus` [#hookshorthandstatus]
Object of boolean status flags returned alongside the `status` string:
```ts
type HookShorthandStatus = {
isIdle: boolean;
isExecuting: boolean;
isTransitioning: boolean;
isPending: boolean; // isExecuting || isTransitioning
hasSucceeded: boolean;
hasErrored: boolean;
hasNavigated: boolean;
};
```
## See also [#see-also]
* [Hooks guide](/docs/guides/hooks): practical guide with patterns and examples
* [Optimistic updates](/docs/guides/optimistic-updates): `useOptimisticAction` in depth
* [Framework navigation/errors](/docs/advanced/framework-errors): `onNavigation` and `hasNavigated` behavior
* [Form actions](/docs/guides/form-actions): compare `useAction`, `useStateAction`, and React's `useActionState`
* [Type utilities](/docs/api/type-utilities): `InferUseActionHookReturn` and related types
# SafeActionClient (/docs/api/safe-action-client)
The `SafeActionClient` class is the core of next-safe-action. It provides a chainable, immutable API for building type-safe server actions. Each method returns a **new** client instance, the original is never modified.
```ts
import { createSafeActionClient } from "next-safe-action";
const actionClient = createSafeActionClient();
```
## `.use()` [#use]
Add a middleware function to the action execution chain. Cannot be called after `useValidated()`.
```ts
client.use(middlewareFn)
```
**Parameters:**
The middleware function receives:
**Returns:** A new `SafeActionClient` with `NextCtx` merged into the context type.
```ts
const authClient = actionClient.use(async ({ next }) => {
const session = await getSession();
if (!session) throw new Error("Unauthorized");
return next({ ctx: { user: session.user } });
});
// authClient now has ctx: { user: User }
```
***
## `.useValidated()` [#usevalidated]
Add a validated middleware function that runs **after** input validation. Only available after `inputSchema()` or `bindArgsSchemas()` has been called. Cannot be followed by `inputSchema()`, `bindArgsSchemas()`, or `use()`.
For most middleware, prefer [`.use()`](#use) instead. `.useValidated()` is designed for the specific cases where your middleware logic depends on the validated `parsedInput`, such as resource ownership checks or input-dependent authorization.
```ts
client.useValidated(middlewareFn)
```
**Parameters:**
The validated middleware function receives:
**Returns:** A new `SafeActionClient` with `NextCtx` merged into the context type. After calling `useValidated()`, `inputSchema()`, `bindArgsSchemas()`, and `use()` are no longer callable (TypeScript error).
```ts
const protectedAction = authClient
.inputSchema(z.object({ postId: z.string() }))
.useValidated(async ({ parsedInput, ctx, next }) => {
const post = await db.post.findUnique({ where: { id: parsedInput.postId } });
if (post?.authorId !== ctx.user.id) throw new Error("Forbidden");
return next({ ctx: { post } });
});
// protectedAction now has ctx: { user: User, post: Post }
```
`useValidated()` middleware is completely skipped if input validation fails. It only runs when all schemas pass.
***
## `.metadata()` [#metadata]
Set metadata for the action. Only available when a metadata schema has been defined via `defineMetadataSchema` in [`createSafeActionClient`](/docs/api/create-safe-action-client).
```ts
client.metadata(data)
```
**Parameters:**
**Returns:** A new `SafeActionClient` with metadata provided.
```ts
const myAction = actionClient
.metadata({ actionName: "createUser" })
.action(async ({ parsedInput, metadata }) => {
console.log(metadata.actionName); // "createUser"
});
```
When a metadata schema is defined, you **must** call `.metadata()` before `.action()` or `.stateAction()`. TypeScript will error if you forget.
***
## `.inputSchema()` [#inputschema]
Define the input validation schema. Accepts a Standard Schema validator (Zod, Valibot, ArkType, etc.) or an async factory function that returns one.
```ts
client.inputSchema(schema, utils?)
```
**Parameters:**
**Returns:** A new `SafeActionClient` with typed `parsedInput`.
```ts
// Direct schema
const action = actionClient
.inputSchema(z.object({ name: z.string() }))
.action(async ({ parsedInput }) => {
// parsedInput: { name: string }
});
// Async factory (for i18n or extending previous schemas)
const action = actionClient
.inputSchema(async () => {
const t = await getTranslations();
return z.object({ name: z.string().min(2, t("name.tooShort")) });
})
.action(async ({ parsedInput }) => { /* ... */ });
```
`.schema()` is a deprecated alias for `.inputSchema()`. Use `.inputSchema()` instead.
`.inputSchema()` cannot be called after `.useValidated()`. TypeScript will report an error if you try.
***
## `.outputSchema()` [#outputschema]
Define the output data validation schema. The action's return value is validated against this schema.
```ts
client.outputSchema(schema)
```
**Parameters:**
**Returns:** A new `SafeActionClient` with typed and validated output data.
```ts
const action = actionClient
.outputSchema(z.object({ id: z.string(), created: z.boolean() }))
.action(async () => {
return { id: "123", created: true };
// TypeScript + runtime validation ensures this shape
});
```
***
## `.bindArgsSchemas()` [#bindargsschemas]
Define validation schemas for [bind arguments](/docs/advanced/bind-arguments). Bind args are additional arguments bound to the action function before the main input.
```ts
client.bindArgsSchemas(schemas)
```
**Parameters:**
**Returns:** A new `SafeActionClient` with typed bind argument inputs.
```ts
const action = actionClient
.inputSchema(z.object({ title: z.string() }))
.bindArgsSchemas([z.string().uuid()]) // bind arg: projectId
.action(async ({ parsedInput, bindArgsParsedInputs: [projectId] }) => {
// parsedInput: { title: string }
// projectId: string
});
// In a component:
const boundAction = action.bind(null, projectId);
```
`.bindArgsSchemas()` cannot be called after `.useValidated()`. TypeScript will report an error if you try.
***
## `.action()` [#action]
Define the server-side code for the action. This terminates the builder chain and returns the callable action function.
```ts
client.action(serverCodeFn, utils?)
```
**Parameters:**
The `serverCodeFn` receives a single argument object:
**Returns:** A `SafeActionFn`, a callable async function.
***
## `.stateAction()` [#stateaction]
Define a stateful server action for use with the `useStateAction` hook or React's `useActionState`.
```ts
client.stateAction(serverCodeFn, utils?)
```
Same as `.action()`, but the `serverCodeFn` receives a second argument `utils` with access to `prevResult`:
**Returns:** A `SafeStateActionFn`, a callable async function compatible with `useActionState`.
***
## `ActionCallbacks` (action callbacks) [#actioncallbacks-action-callbacks]
The optional second argument to `.action()` and `.stateAction()`:
In `onError`, `onSettled`, and `onNavigation` callbacks, context added by `useValidated()` middleware is optional in the `ctx` type. Context from `use()` middleware is always present, but `useValidated()` context may not exist if validation failed before validated middleware could run.
```ts
export const myAction = actionClient
.inputSchema(schema)
.action(
async ({ parsedInput }) => {
return await doSomething(parsedInput);
},
{
onSuccess: async ({ data, metadata }) => {
console.log("Success:", data);
},
onError: async ({ error }) => {
await reportError(error.serverError);
},
}
);
```
## Method chaining order [#method-chaining-order]
Methods can be called in any order with a few constraints: `use()` must come before `useValidated()`, schemas must come before `useValidated()`, and the final call must be `.action()` / `.stateAction()`.
Typical order:
```ts
actionClient
.use(middleware) // 1. Add pre-validation middleware (repeatable)
.metadata(data) // 2. Set metadata (if schema defined)
.inputSchema(schema) // 3. Define input validation
.bindArgsSchemas([...]) // 4. Define bind args (optional, must be before useValidated)
.useValidated(middleware) // 5. Add post-validation middleware (repeatable, requires schema)
.outputSchema(schema) // 6. Define output validation (optional)
.action(fn, utils) // 7. Define server code (terminal)
```
## See also [#see-also]
* [Action client](/docs/concepts/action-client): conceptual overview and immutability pattern
* [Middleware guide](/docs/guides/middleware): practical patterns for `.use()` and `.useValidated()`
* [`createSafeActionClient()`](/docs/api/create-safe-action-client): creating the client instance
* [`createMiddleware()`](/docs/api/create-middleware) / [`createValidatedMiddleware()`](/docs/api/create-validated-middleware): standalone middleware factories
* [Types reference](/docs/api/types): all exported TypeScript types
# Type utilities (/docs/api/type-utilities)
next-safe-action exports several utility types for inferring types from action functions, clients, and middleware. These are useful when you need to reference action types in other parts of your code.
All type utilities are imported from the main entry point:
```ts
import type {
InferSafeActionFnInput,
InferSafeActionFnResult,
InferMiddlewareFnNextCtx,
InferCtx,
InferMetadata,
InferServerError,
} from "next-safe-action";
```
## `InferSafeActionFnInput` [#infersafeactionfninput]
Infer the input types (both client-side and parsed) from an action function.
```ts
type InferSafeActionFnInput
```
**Produces:**
```ts
{
clientInput: StandardSchemaV1.InferInput;
bindArgsClientInputs: InferInputArray;
parsedInput: StandardSchemaV1.InferOutput;
bindArgsParsedInputs: InferOutputArray;
}
```
**Works with:** `SafeActionFn`, `SafeStateActionFn`
```ts
import type { InferSafeActionFnInput } from "next-safe-action";
import { myAction } from "./actions";
type MyInput = InferSafeActionFnInput;
// MyInput.clientInput: what you pass to execute()
// MyInput.parsedInput: what the server code receives
// MyInput.bindArgsClientInputs: bound arg types (input side)
// MyInput.bindArgsParsedInputs: bound arg types (parsed side)
```
***
## `InferSafeActionFnResult` [#infersafeactionfnresult]
Infer the result type from an action function.
```ts
type InferSafeActionFnResult
```
**Produces:** `SafeActionResult`
**Works with:** `SafeActionFn`, `SafeStateActionFn`
```ts
import type { InferSafeActionFnResult } from "next-safe-action";
import { myAction } from "./actions";
type MyResult = InferSafeActionFnResult;
// MyResult.data: the successful return type
// MyResult.serverError: the server error type
// MyResult.validationErrors: the validation errors type
```
***
## `InferMiddlewareFnNextCtx` [#infermiddlewarefnnextctx]
Infer the next context type that a middleware function provides via `next({ ctx })`.
```ts
type InferMiddlewareFnNextCtx
```
**Produces:** The `NextCtx` type parameter from `MiddlewareFn`.
**Works with:** `MiddlewareFn`
```ts
import type { InferMiddlewareFnNextCtx } from "next-safe-action";
import { authMiddleware } from "./middleware";
type AuthCtx = InferMiddlewareFnNextCtx;
// { user: { id: string; role: string } }
```
***
## `InferCtx` [#inferctx]
Infer the current context type from a safe action client or middleware function.
```ts
type InferCtx
```
**Produces:** The `Ctx` type, the accumulated context up to that point in the chain.
**Works with:** `SafeActionClient`, `MiddlewareFn`
```ts
import type { InferCtx } from "next-safe-action";
import { authClient } from "./safe-action";
type AuthClientCtx = InferCtx;
// { user: { id: string; role: string } }
```
***
## `InferMetadata` [#infermetadata]
Infer the metadata type from a safe action client or middleware function.
```ts
type InferMetadata
```
**Produces:** The `Metadata` type, inferred from the metadata schema or `undefined` if none.
**Works with:** `SafeActionClient`, `MiddlewareFn`
```ts
import type { InferMetadata } from "next-safe-action";
import { actionClient } from "./safe-action";
type MyMetadata = InferMetadata;
// { actionName: string } (if defineMetadataSchema was set)
// undefined (if no metadata schema)
```
***
## `InferServerError` [#inferservererror]
Infer the server error type from a client, middleware, or action function.
```ts
type InferServerError
```
**Produces:** The `ServerError` type, which defaults to `string` unless customized via `handleServerError`.
**Works with:** `SafeActionClient`, `MiddlewareFn`, `SafeActionFn`, `SafeStateActionFn`
```ts
import type { InferServerError } from "next-safe-action";
import { actionClient } from "./safe-action";
import { myAction } from "./actions";
type ClientError = InferServerError; // string (default)
type ActionError = InferServerError; // string (inherited)
```
***
## Hook inference types [#hook-inference-types]
These are imported from `next-safe-action/hooks`:
```ts
import type {
InferUseActionHookReturn,
InferUseOptimisticActionHookReturn,
InferUseStateActionHookReturn,
} from "next-safe-action/hooks";
```
### `InferUseActionHookReturn` [#inferuseactionhookreturn]
Infer the return type of `useAction` for a given action function. The inferred type is a discriminated union keyed on `status` and shorthand booleans, so checking any discriminant narrows `result` to the matching branch.
```ts
type InferUseActionHookReturn
```
**Works with:** `SafeActionFn`
### `InferUseOptimisticActionHookReturn` [#inferuseoptimisticactionhookreturn]
Infer the return type of `useOptimisticAction` for a given action function and state type. Includes `optimisticState` plus the same discriminated union narrowing as `InferUseActionHookReturn`.
```ts
type InferUseOptimisticActionHookReturn
```
**Works with:** `SafeActionFn`
### `InferUseStateActionHookReturn` [#inferusestateactionhookreturn]
Infer the return type of `useStateAction` for a given stateful action function. Includes `formAction` plus the same discriminated union narrowing as `InferUseActionHookReturn`.
```ts
type InferUseStateActionHookReturn
```
**Works with:** `SafeStateActionFn`
## See also [#see-also]
* [Types reference](/docs/api/types): all exported TypeScript types
* [Hooks API](/docs/api/hooks-api): the hooks these types infer from
* [Action result](/docs/concepts/action-result): understanding `InferSafeActionFnResult`
# Types (/docs/api/types)
This page documents all the TypeScript types exported by next-safe-action. Types are exported from the main `next-safe-action` entry point unless otherwise noted.
## Core types [#core-types]
### `SafeActionResult` [#safeactionresult]
The result object returned by every action execution. Modeled as a **discriminated union** so that at most one of `data`, `serverError`, and `validationErrors` is populated — checking one field narrows the others to `undefined`.
```ts
type SafeActionResult =
| { data?: undefined; serverError?: undefined; validationErrors?: undefined } // idle / framework navigation
| { data: Data; serverError?: undefined; validationErrors?: undefined } // success
| { data?: undefined; serverError: ServerError; validationErrors?: undefined } // server error
| { data?: undefined; serverError?: undefined; validationErrors: ShapedErrors }; // validation failure
```
In compound-error scenarios where the runtime could otherwise produce multiple populated fields (middleware calling `next()` twice, or invalid bind args combined with invalid main input), a fixed precedence is applied: `validationErrors` > `serverError` > `data`. See [Action result](/docs/concepts/action-result#reading-the-result) for details.
***
### `SafeActionFn` [#safeactionfn]
The callable function type returned by `.action()`.
```ts
type SafeActionFn = (
...clientInputs: [...bindArgsInputs: InferInputArray, input: InferInput]
) => Promise>;
```
When bind args are defined, they appear as leading parameters. The main input is always the last parameter.
***
### `SafeStateActionFn` [#safestateactionfn]
The callable function type returned by `.stateAction()`.
```ts
type SafeStateActionFn = (
...clientInputs: [
...bindArgsInputs: InferInputArray,
prevResult: SafeActionResult,
input: InferInput,
]
) => Promise>;
```
Same as `SafeActionFn` but includes `prevResult` as the second-to-last parameter, before the main input.
***
## Middleware types [#middleware-types]
### `MiddlewareFn` [#middlewarefn]
The function type for middleware defined via `.use()` or `createMiddleware().define()`.
```ts
type MiddlewareFn = (opts: {
clientInput: unknown;
bindArgsClientInputs: unknown[];
ctx: Ctx;
metadata: Metadata;
next: (opts?: { ctx?: NC }) => Promise>;
}) => Promise>;
```
***
### `MiddlewareResult` [#middlewareresult]
The result type returned by the `next()` function inside middleware. Carries the same readable fields as `SafeActionResult` plus execution metadata (navigation kind, parsed inputs, context, success flag).
```ts
type MiddlewareResult = {
data?: any;
serverError?: ServerError;
validationErrors?: any;
navigationKind?: NavigationKind;
parsedInput?: unknown;
bindArgsParsedInputs?: unknown[];
ctx?: object;
success: boolean;
};
```
This is intentionally a flat object rather than an intersection with `SafeActionResult`. Because `SafeActionResult` is now a discriminated union, intersecting it would prevent middleware from mutating `data`/`serverError`/`validationErrors` while the chain executes. The set of readable fields is unchanged from previous versions.
***
## Server code types [#server-code-types]
### `ServerCodeFn` [#servercodefn]
The function type for the server code passed to `.action()`.
```ts
type ServerCodeFn = (args: {
parsedInput: InferOutput | undefined;
clientInput: InferInput | undefined;
bindArgsParsedInputs: InferOutputArray;
bindArgsClientInputs: InferInputArray;
ctx: Ctx;
metadata: Metadata;
}) => Promise;
```
***
### `StatefulServerCodeFn` [#statefulservercodefn]
The function type for the server code passed to `.stateAction()`. Same as `ServerCodeFn` but with a second `utils` argument.
```ts
type StatefulServerCodeFn = (
args: {
parsedInput: InferOutput | undefined;
clientInput: InferInput | undefined;
bindArgsParsedInputs: InferOutputArray;
bindArgsClientInputs: InferInputArray;
ctx: Ctx;
metadata: Metadata;
},
utils: {
prevResult: SafeActionResult;
}
) => Promise;
```
***
## Configuration types [#configuration-types]
### `CreateClientOpts` [#createclientopts]
Options passed to [`createSafeActionClient()`](/docs/api/create-safe-action-client).
```ts
type CreateClientOpts = {
defineMetadataSchema?: () => MetadataSchema;
handleServerError?: HandleServerErrorFn;
defaultValidationErrorsShape?: ErrorsFormat;
throwValidationErrors?: boolean;
};
```
***
### `ActionCallbacks` [#actioncallbacks]
Server-side callbacks and options passed as the second argument to `.action()` and `.stateAction()`.
```ts
type ActionCallbacks = {
throwServerError?: boolean;
throwValidationErrors?: boolean | {
overrideErrorMessage: (validationErrors: ShapedErrors) => Promise;
};
onSuccess?: (args: { data?, metadata, ctx?, clientInput, bindArgsClientInputs, parsedInput, bindArgsParsedInputs }) => Promise;
onNavigation?: (args: { metadata, ctx?, clientInput, bindArgsClientInputs, navigationKind }) => Promise;
onError?: (args: { error, metadata, ctx?, clientInput, bindArgsClientInputs }) => Promise;
onSettled?: (args: { result, metadata, ctx?, clientInput, bindArgsClientInputs, navigationKind? }) => Promise;
};
```
***
### `HandleServerErrorFn` [#handleservererrorfn]
The type for the `handleServerError` callback.
```ts
type HandleServerErrorFn = (
error: Error,
utils: ServerErrorFunctionUtils
) => MaybePromise;
```
***
### `ServerErrorFunctionUtils` [#servererrorfunctionutils]
Utils passed to `handleServerError`.
```ts
type ServerErrorFunctionUtils = {
clientInput: unknown;
bindArgsClientInputs: unknown[];
ctx: object;
metadata: InferOutput | undefined;
};
```
***
## Hook result types [#hook-result-types]
These types describe the `result` shape within each branch of the hook return discriminated union. They are exported from `next-safe-action/hooks`.
### `NormalizeActionResult` [#normalizeactionresult]
Collapses the void-success branch of a `SafeActionResult` union. When an action returns nothing (`void`), the `{ data: void }` branch is dropped so that `result.data` is exactly `undefined` rather than `void | undefined`. Applied automatically to hook `result` and `executeAsync` return types.
```ts
type NormalizeActionResult = R extends { data: infer D }
? [D] extends [void]
? Exclude
: R
: R;
```
When `Data` is not `void`, the type passes through unchanged.
***
### `HookIdleResult` [#hookidleresult]
The result shape when no action has completed yet (idle, executing, navigated). All fields are `undefined`.
```ts
type HookIdleResult = {
data?: undefined;
serverError?: undefined;
validationErrors?: undefined;
};
```
***
### `HookSuccessResult` [#hooksuccessresult]
The result shape for the success branch. For void-returning actions, collapses to `HookIdleResult`.
```ts
type HookSuccessResult = [Data] extends [void]
? HookIdleResult
: { data: Data; serverError?: undefined; validationErrors?: undefined };
```
***
### `HookErrorResult` [#hookerrorresult]
The result shape for the error branch. Includes the idle shape for thrown errors (where `result` is `{}` and the error is captured internally).
```ts
type HookErrorResult =
| HookIdleResult
| { data?: undefined; serverError: ServerError; validationErrors?: undefined }
| { data?: undefined; serverError?: undefined; validationErrors: ShapedErrors };
```
***
## Validation error types [#validation-error-types]
### `ValidationErrors` [#validationerrors]
The formatted validation errors type, mirroring the schema structure.
```ts
type ValidationErrors = Schema extends StandardSchemaV1
? InferOutput extends PrimitiveOrArray
? { _errors?: string[] }
: { _errors?: string[] } & SchemaErrors>
: undefined;
```
Each level of the schema can have an `_errors` array. Nested objects create nested error objects.
***
### `FlattenedValidationErrors` [#flattenedvalidationerrors]
The flattened validation errors type, with top-level `formErrors` and `fieldErrors`.
```ts
type FlattenedValidationErrors = {
formErrors: string[];
fieldErrors: {
[K in keyof Omit]?: string[];
};
};
```
***
### `HandleValidationErrorsShapeFn` [#handlevalidationerrorsshapefn]
Function type for custom validation error shaping.
```ts
type HandleValidationErrorsShapeFn = (
validationErrors: ValidationErrors,
utils: {
clientInput: InferInput | undefined;
bindArgsClientInputs: InferInputArray;
metadata: Metadata;
ctx: Ctx;
}
) => Promise;
```
***
## Navigation types [#navigation-types]
### `NavigationKind` [#navigationkind]
Union type representing framework navigation functions.
```ts
type NavigationKind = "redirect" | "notFound" | "forbidden" | "unauthorized" | "other";
```
***
## Enums and constants [#enums-and-constants]
### `ValidationErrorsFormat` [#validationerrorsformat]
The default validation errors shape type.
```ts
type ValidationErrorsFormat = "formatted" | "flattened";
```
***
## Utility types [#utility-types]
### `Prettify` [#prettify]
Makes complex intersection types readable in IDE hover tooltips.
```ts
type Prettify = { [K in keyof T]: T[K] } & {};
```
### `MaybePromise` [#maybepromise]
Accepts a value or a promise of a value.
```ts
type MaybePromise = Promise | T;
```
### `MaybeArray` [#maybearray]
Accepts a value or an array of values.
```ts
type MaybeArray = T | T[];
```
## See also [#see-also]
* [Type utilities](/docs/api/type-utilities): `Infer*` types for extracting types from actions and clients
* [Action result](/docs/concepts/action-result): understanding `SafeActionResult`
* [Hooks API](/docs/api/hooks-api): `HookCallbacks`, `HookActionStatus`, and hook return types
# Validation utilities (/docs/api/validation-utilities)
next-safe-action exports several utility functions and constants for working with validation errors.
All utilities are imported from the main entry point:
```ts
import {
returnValidationErrors,
returnServerError,
flattenValidationErrors,
formatValidationErrors,
DEFAULT_SERVER_ERROR_MESSAGE,
} from "next-safe-action";
```
## `returnValidationErrors()` [#returnvalidationerrors]
Throw validation errors from server action code. This function **never returns**. It throws internally and the error is caught by the action builder and returned as `validationErrors` in the result.
```ts
function returnValidationErrors(
schema: S,
validationErrors: ValidationErrors
): never;
```
**Parameters:**
**Returns:** `never`, this function always throws.
```ts
export const signUp = actionClient
.inputSchema(z.object({
email: z.string().email(),
username: z.string().min(3),
}))
.action(async ({ parsedInput }) => {
const emailExists = await db.user.findByEmail(parsedInput.email);
if (emailExists) {
// Throws internally, code below this line never executes
return returnValidationErrors(signUpSchema, {
email: { _errors: ["Email already registered"] },
});
}
// Form-level errors (not tied to a specific field)
return returnValidationErrors(signUpSchema, {
_errors: ["Registration is currently disabled"],
});
});
```
`returnValidationErrors` accepts both direct schemas and async schema factory functions. When using an async factory (for i18n), pass the factory function itself.
***
## `returnServerError()` [#returnservererror]
Return a typed, expected server error to the client from server action code or middleware. This function **never returns**. It throws internally and the error is caught by the action builder and returned as `serverError` in the result, **bypassing `handleServerError`**.
```ts
function returnServerError(serverError: SE): never;
```
**Parameters:**
**Returns:** `never`, this function always throws.
```ts
export const buyProduct = actionClient
.inputSchema(z.object({ productId: z.string() }))
.action(async ({ parsedInput }) => {
const product = await db.product.find(parsedInput.productId);
if (!product.inStock) {
// Throws internally, code below this line never executes
returnServerError({ code: "OUT_OF_STOCK", message: "This product is sold out" });
}
// ...
});
```
Since `SE` is inferred from the argument, the payload isn't checked against the client's `ServerError` type by default. Enforce it at the call site with an explicit generic or `satisfies`, or export a typed alias next to your action client:
```ts
returnServerError({ code: "OUT_OF_STOCK", message: "This product is sold out" });
// or
returnServerError({ code: "OUT_OF_STOCK", message: "This product is sold out" } satisfies AppServerError);
// or, recommended: a typed alias in lib/safe-action.ts
export const returnAppError: (e: AppServerError) => never = returnServerError;
```
See [Typing the error payload](/docs/concepts/error-handling#typing-the-error-payload) for the full explanation.
The payload is JSON-encoded onto the error `digest`, so it also works when thrown inside a Next.js `"use cache"` scope with `cacheComponents` enabled. See [Error handling](/docs/concepts/error-handling#expected-server-errors-with-returnservererror) for more details.
***
## `flattenValidationErrors()` [#flattenvalidationerrors]
Transform formatted validation errors into a flat structure with `formErrors` and `fieldErrors`. Discards errors for nested fields (only keeps one level deep).
```ts
function flattenValidationErrors>(
validationErrors: VE
): FlattenedValidationErrors;
```
**Parameters:**
**Returns:** `FlattenedValidationErrors`, an object with `formErrors: string[]` and `fieldErrors: { [key]: string[] }`.
```ts
// Input (formatted shape):
{
_errors: ["Passwords don't match"],
name: { _errors: ["Too short"] },
address: { street: { _errors: ["Required"] } },
}
// Output (flattened shape):
{
formErrors: ["Passwords don't match"],
fieldErrors: {
name: ["Too short"],
// address.street is discarded (nested)
},
}
```
### Usage with `handleValidationErrorsShape` [#usage-with-handlevalidationerrorsshape]
```ts
import { flattenValidationErrors } from "next-safe-action";
export const myAction = actionClient
.inputSchema(schema, {
handleValidationErrorsShape: (ve) => flattenValidationErrors(ve),
})
.action(async ({ parsedInput }) => { /* ... */ });
```
***
## `formatValidationErrors()` [#formatvalidationerrors]
Identity function that returns the formatted validation errors as-is. Useful as a named reference when you want to be explicit about using the default shape.
```ts
function formatValidationErrors>(
validationErrors: VE
): VE;
```
***
## `DEFAULT_SERVER_ERROR_MESSAGE` [#default_server_error_message]
The default error message returned to the client when a server error occurs and no custom `handleServerError` is provided.
```ts
const DEFAULT_SERVER_ERROR_MESSAGE: string;
// Value: "Something went wrong while executing the operation."
```
This constant is useful when you want to check if the client received the default error message, or when building custom error handlers that should fall back to the default.
```ts
import { DEFAULT_SERVER_ERROR_MESSAGE } from "next-safe-action";
const actionClient = createSafeActionClient({
handleServerError: (error) => {
if (error instanceof AuthError) {
return "Authentication failed";
}
return DEFAULT_SERVER_ERROR_MESSAGE;
},
});
```
## See also [#see-also]
* [Custom validation errors](/docs/advanced/custom-validation-errors): guide for customizing error shapes
* [Error handling](/docs/concepts/error-handling): the complete error taxonomy
* [Error classes](/docs/api/error-classes): all exported error classes
# Executing actions (/docs/guides/executing-actions)
There are four ways to execute a safe action from a Client Component. Each approach serves different needs:
## Comparison [#comparison]
Given the same action:
```ts title="src/app/actions.ts"
"use server";
import { z } from "zod";
import { actionClient } from "@/lib/safe-action";
export const greetUser = actionClient
.inputSchema(z.object({ name: z.string() }))
.action(async ({ parsedInput }) => {
return { greeting: `Hello, ${parsedInput.name}!` };
});
```
Here's how each method calls it:
```tsx title="src/app/page.tsx"
"use client";
import { greetUser } from "./actions";
export default function Page() {
const handleClick = async () => {
const result = await greetUser({ name: "Alice" });
if (result.data) {
alert(result.data.greeting);
}
};
return ;
}
```
**Use when**: You need a simple one-off call, or you're calling from a Server Component or event handler where you don't need reactive UI updates.
```tsx title="src/app/page.tsx"
"use client";
import { useAction } from "next-safe-action/hooks";
import { greetUser } from "./actions";
export default function Page() {
const { execute, result, isExecuting } = useAction(greetUser, {
onSuccess: ({ data }) => alert(data.greeting),
});
return (
);
}
```
**Use when**: You need loading states, status tracking, lifecycle callbacks, or any reactive UI behavior. This is the most common approach for interactive Client Components.
```tsx title="src/app/page.tsx"
"use client";
import { useActionState } from "react";
import { greetUser } from "./actions";
export default function Page() {
const [result, dispatch] = useActionState(greetUser, {});
return (
);
}
```
**Use when**: You need progressive enhancement (form works without JavaScript), or you want to use HTML form patterns with `FormData` input. See the [Form Actions guide](/docs/guides/form-actions) for details.
## Which method should I use? [#which-method-should-i-use]
| Need | Method |
| ---------------------------------------------- | -------------------------- |
| Simple call, no loading UI | Direct call |
| Loading states, callbacks, reactive result | `useAction` hook |
| Forms with callbacks, status, and `prevResult` | `useStateAction` hook |
| Optimistic UI updates | `useOptimisticAction` hook |
| Progressive enhancement / no-JS forms | `useActionState` (React) |
| Server Component calling an action | Direct call |
## What's next? [#whats-next]
Deep dive into useAction with status tracking, callbacks, and async execution.
Build forms with progressive enhancement using next-safe-action.
Update the UI instantly while the server processes your action.
# Form actions (/docs/guides/form-actions)
next-safe-action works with HTML forms using `FormData` as input. This enables **progressive enhancement**, meaning forms that work even without JavaScript.
## Stateless vs stateful [#stateless-vs-stateful]
There are two approaches to form actions:
Use `useAction` when you want full control over execution and don't need the form to work without JavaScript:
### Define the action with FormData input [#define-the-action-with-formdata-input]
When a form submits, the browser sends `FormData`. Use a library like `zod-form-data` to validate it:
npm
pnpm
yarn
bun
```bash
npm install zod-form-data
```
```bash
pnpm add zod-form-data
```
```bash
yarn add zod-form-data
```
```bash
bun add zod-form-data
```
```ts title="src/app/actions.ts"
"use server";
import { z } from "zod";
import { zfd } from "zod-form-data";
import { actionClient } from "@/lib/safe-action";
const schema = zfd.formData({
email: zfd.text(z.string().email()),
password: zfd.text(z.string().min(8)),
});
export const loginAction = actionClient
.inputSchema(schema)
.action(async ({ parsedInput: { email, password } }) => {
const user = await authenticate(email, password);
return { userId: user.id };
});
```
### Create the form component [#create-the-form-component]
```tsx title="src/app/login.tsx"
"use client";
import { useAction } from "next-safe-action/hooks";
import { useRef } from "react";
import { loginAction } from "./actions";
export default function LoginForm() {
const formRef = useRef(null);
const { execute, result, isExecuting } = useAction(loginAction, {
onSuccess: () => {
formRef.current?.reset();
},
});
return (
);
}
```
Use `useStateAction` when you want `
Use React's `useActionState` directly for **progressive enhancement**, where the form works even without JavaScript. This approach has no lifecycle callbacks or navigation tracking, but forms submit natively before React hydrates:
### Define a state action [#define-a-state-action-1]
Use `.stateAction()` instead of `.action()` for stateful actions:
```ts title="src/app/actions.ts"
"use server";
import { z } from "zod";
import { zfd } from "zod-form-data";
import { actionClient } from "@/lib/safe-action";
const schema = zfd.formData({
email: zfd.text(z.string().email()),
password: zfd.text(z.string().min(8)),
});
export const loginAction = actionClient
.inputSchema(schema)
.stateAction(async ({ parsedInput: { email, password } }) => {
const user = await authenticate(email, password);
return { userId: user.id };
});
```
### Create the form with useActionState [#create-the-form-with-useactionstate]
```tsx title="src/app/login.tsx"
"use client";
import { useActionState } from "react";
import { loginAction } from "./actions";
export default function LoginForm() {
const [result, dispatch, isPending] = useActionState(loginAction, {});
return (
);
}
```
**Progressive enhancement**: The `action={dispatch}` pattern means the form submits natively, even before React hydrates on the client. The server processes the action and returns updated HTML. Once JavaScript loads, the form becomes interactive with `isPending` states and instant validation.
## When to use each approach [#when-to-use-each-approach]
| Feature | `useAction` | `useStateAction` | `useActionState` (React) |
| ---------------------- | ------------------------------------- | ------------------------------ | ------------------------------- |
| Works without JS | No | No | Yes |
| Previous result access | No | Yes (via `stateAction`) | Yes (via `stateAction`) |
| Form action support | No (`onSubmit` only) | Yes (`formAction`) | Yes (`dispatch`) |
| Loading states | `isExecuting`, `isPending` | `isExecuting`, `isPending` | `isPending` |
| Lifecycle callbacks | Full | Full | None |
| Navigation tracking | `onNavigation`, `hasNavigated` | `onNavigation`, `hasNavigated` | Error boundary only |
| `throwOnNavigation` | Yes | Yes | N/A (always throws) |
| `reset()` | Yes | Yes | No |
| `executeAsync` | Yes | Yes | No |
| Action method | `.action()` | `.stateAction()` | `.stateAction()` |
| Best for | Interactive UI, programmatic triggers | Forms with callbacks and state | Forms that must work without JS |
* **Use `useAction`** when you don't need previous result access, your triggers are programmatic (buttons, events), or you're building interactive UI that doesn't use `
