safe-action-advanced

# next-safe-action Advanced Features ## Overview | Feature | Use Case | |---|---| | [Bind arguments](./bind-arguments.md) | Pass extra args to actions via `.bind()` (e.g., resource IDs) | | [Metadata](./metadata.md) | Attach typed metadata to actions for use in middleware | | [Framework errors](./framework-errors.md) | Handle redirect, notFound, forbidden, unauthorized in actions | | [Type utilities](./type-utilities.md) | Infer types from action functions and middleware | ## Server-Level Action Callbacks The second argument to `.action()` accepts callbacks that run **on the server** (not client-side hooks): ```ts export const createPost = authActionClient .inputSchema(schema) .action( async ({ parsedInput, ctx }) => { const post = await db.post.create(parsedInput); return post; }, { onSuccess: async ({ data, parsedInput, ctx, metadata, clientInput }) => { // Runs on the server after successful execution await invalidateCache("posts"); }, onError: async ({ error, metadata, ctx, clientInput, bindArgsClientInputs }) => { // error: { serverError?, validationErrors? } await logError(error); }, onSettled: async ({ result }) => { // Always runs await recordMetrics(result); }, onNavigation: async ({ navigationKind }) => { // Runs when a framework error (redirect, notFound, etc.) occurs console.log("Navigation:", navigationKind); }, } ); ``` These are distinct from hook callbacks (`useAction({ onSuccess })`) — server callbacks run in the Node.js runtime, hook callbacks run in the browser. ## throwServerError Re-throw server errors instead of returning them as `result.serverError`: ```ts export const myAction = actionClient .inputSchema(schema) .action(serverCodeFn, { throwServerError: true, // The handled server error (return of handleServerError) is thrown }); ``` Don't confuse this with `returnServerError()`: `throwServerError` throws the *handled* error (post-`handleServerError`) instead of returning it, while `returnServerError(payload)` returns a typed *expected* error in `result.serverError`, bypassing `handleServerError` entirely (see the safe-action-client skill's error-handling doc).