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