Agent skill · software engineering · mohamed-hossam1
next-action-handler
Use when setting up or using next-action-handler, next-safe-action, actionClient/authedActionClient, action metadata/actionName, validationErrors, outputSchema, handleServerError, better-auth errors, or pino logging.
Why this skill is useful
Adds a standardized server action layer with specific error handling and logging patterns that the AI wouldn't reliably generate on its own.
What it needs
Requires next-action-handler installed locally. About 3k tokens when loaded. Last updated 2026-05-30. 8 stars on the source repository.
What this skill does
next-action-handler Skill What It Does next-action-handler installs a server action layer built on next-safe-action, better-auth, pino, and zod. It standardizes errors, logging, and auth context. Installation If you want a local dev dependency, install it first. Otherwise skip to Usage. Usage From the project root, run the installer: @latest forces npx to use the newest published version. The installer applies the full handler setup in one pass, with no component selection. Install path detection order: 1. lib/ -> lib/next-action-handler/ 2. app/lib/ -> app/lib/next-action-handler/ 3. Otherwise create lib/next-action-handler/ Dependencies installed: better-auth, next-safe-action, pino, pino-pretty, server-only, zod. Required: auth-helpers.ts safe-action.ts imports requireUser from ../auth-helpers. Create it before using authedActionClient. Action Clients and Metadata Every action must call .metadata({ actionName }). The metadata schema requires it and the logger uses it. Result Shape and Input Validation actionClient returns a SafeActionResult union. Only one of data, serverError, or validationErrors is present. Input schema failures land in validationErrors, not serverError. Output Validation outputSchema mismatches become serverError (not validationErrors). Output validation failures are detected as ActionOutputDataValidationError and mapped to a PublicServerError with code INTERNALSERVERERROR and message Unexpected response. Please try again. The error is normalized and logged using InternalServerError("Action output validation failed", error). handleServerError returns a PublicServerError shape { code, message } and uses DEFAULTSERVERERRORMESSAGE when expose is false for all other errors. If you customize handleServerError, keep the ActionOutputDataValidationError branch from safe-action.ts. See patterns for a copy-paste block. Error Classes Throw these inside actions. They are normalized and logged; only safe messages reach the client. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills mohamed-hossam1/next-action-handler