Safe Action Advanced

next-safe-action/skills/skills/safe-action-advanced

作者 next-safe-actiona2605bd2e84321245cba8f5718c144a6e4a5fa47無授權條款收錄於 2026年10月9日更新於 2026年10月9日

Use when working with bind arguments, metadata schemas, framework errors (redirect/notFound/forbidden/unauthorized), type inference utilities (InferSafeActionFnInput/Result), or server-level action callbacks

僅含說明Software Development AI & Agents

AI 產生的概覽

next-safe-action 進階功能參考：綁定參數、中介資料、框架錯誤、型別工具與伺服器端回呼。

功能: 這個技能是一份文件式參考，介紹 next-safe-action 函式庫的進階功能。它說明如何透過 .bind() 傳入額外參數、附加供中介軟體使用的具型別中介資料、處理 redirect、notFound、forbidden、unauthorized 等框架錯誤，以及從 action 函式與中介軟體推斷型別。它也記錄了伺服器端 action 回呼（onSuccess、onError、onSettled、onNavigation）與 throwServerError 選項，並附有程式碼範例。
適用情境: 在撰寫或審查 next-safe-action 伺服器端 action，且需要綁定參數、具型別中介資料、框架錯誤處理、型別推斷工具或伺服器端回呼時使用。它面向已經使用該函式庫的開發者，而非一般 TypeScript 問題。
執行需求: 不附帶任何指令碼，僅為說明與參考文件。它假定讀者在 TypeScript 與 Node.js 伺服器端執行環境中使用 next-safe-action 函式庫的專案裡工作。

next-safe-action Advanced Features

Overview

Feature	Use Case
Bind arguments	Pass extra args to actions via `.bind()` (e.g., resource IDs)
Metadata	Attach typed metadata to actions for use in middleware
Framework errors	Handle redirect, notFound, forbidden, unauthorized in actions
Type utilities	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):

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);      },    }  );

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:

export const myAction = actionClient  .inputSchema(schema)  .action(serverCodeFn, {    throwServerError: true,    // The handled server error (return of handleServerError) is thrown  });

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).

來源與署名

來源：next-safe-action/skills位於skills/safe-action-advanced提交a2605bd

授權條款：無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

Safe Action Advanced

next-safe-action Advanced Features

Overview

Server-Level Action Callbacks

throwServerError

來源與署名

更多來自 next-safe-action/skills 的技能

Safe Action Validation Errors

Safe Action Middleware

Safe Action Hooks

Safe Action Testing

Safe Action Client

Safe Action Forms

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices