Skip to content
Skills Library
Programming · Tool integration

next-action-handler

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

Licence
MIT
Last repository change
30.05.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 30.05.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Original author description

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.

How it works

  1. What It Does
  2. Installation
  3. Usage
  4. Required: auth-helpers.ts
  5. Action Clients and Metadata
  6. Result Shape and Input Validation
  7. Output Validation
  8. Error Classes
  9. Error Converters
  10. Logging
Original SKILL.md headings · 212 lines, 805 words
SKILL.md preview
---
name: next-action-handler
description: "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."
metadata:
  author: mohamed-hossam1
  version: 1.0.1
---

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

```bash
npm install -D next-action-handler
```

## Usage

From the project root, run the installer:

```bash
npx next-action-handler@latest add
```

`@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`.

```ts
// Good: required for authedActionClient
import { headers } from "next/headers";
import { auth } from "./auth";
import { UnauthorizedError } from "./next-action-handler/error/errors";

export async function requireUser() {
  const session = await auth.api.getSession({ headers: await headers() });
  if (!session?.user) throw new UnauthorizedError("You must be logged in");
  return session.user;
}
```

## Action Clients and Metadata

Every action must call `.metadata({ actionName })`. The metadata schema requires it and the logger uses it.

```ts
// Good: metadata actionName is required
import { z } from "zod";
import {
  actionClient,
  authedActionClient,
} from "@/lib/next-action-handler/safe-action";
import { db } from "@/lib/db";

export const submitContactForm = actionClient
  .metadata({ actionName: "submitContactForm" })
  .inputSchema(
    z.object({ email: z.string().email(), message: z.string().min(1) }),
  )
  .action(async ({ parsedInput }) => {
    return { success: true, email: parsedInput.email };
  });

export const updateProfile = authedActionClient
  .metadata({ actionName: "updateProfile" })
  .inputSchema(z.object({ displayName: z.string().min(1) }))
  .action(async ({ parsedInput, ctx }) => {
    await db.users.update({
      id: ctx.user.id,
      displayName: parsedInput.displayName,
    });
    return { updated: true };
  });
```

## Result Shape and Input Validation

`actionClient` returns a `SafeActionResult` union. Only one of `data`, `serverError`, or `validationErrors` is present.

```ts
// Good: result union shape
type SafeActionResult<ServerError, Schema, ShapedErrors, Data> =
  | { data: Data; serverError?: undefined; validationErrors?: undefined }
  | { data?: undefined; serverError: ServerError; validationErrors?: undefined }
  | {
      data?: undefined;
      serverError?: undefined;
      validationErrors: ShapedErrors;
    };
```

Input schema failures land in `validationErrors`, not `serverError`.

```ts
// Good: check validationErrors before serverError
import { z } from "zod";
import { actionClient } from "@/lib/next-action-handler/safe-action";

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8, "Password must contain at least 8 characters"),
});

export const loginAction = actionClient
  .metadata({ actionName: "loginAction" })
  .inputSchema(schema)
  .action(async ({ parsedInput }) => {
    return { success: true, email: parsedInput.email };
  });

export async function submitLogin() {
  const result = await loginAction({ email: "bad", password: "short" });

  if (result.validationErrors) {
    console.error(result.validationErrors.email?._errors?.[0]);
    return;
  }
  if (result.serverError) {
    console.error(result.serverError.message);
    return;
  }

  console.log(result.data.email);
}
```

## Output Validation

`outputSchema` mismatches become `serverError` (not `validationErrors`). Output validation failures are detected as `ActionOutputDataValidationError` and mapped to a `PublicServerError` with code `INTERNAL_SERVER_ERROR` 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 `DEFAULT_SERVER_ERROR_MESSAGE` when `expose` is false for all other errors.

```ts
// Good: output validation returns serverError
import { z } from "zod";
import { actionClient } from "@/lib/next-action-handler/safe-action";
import { db } from "@/lib/db";

const outputSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
});

export const getUser = actionClient
  .metadata({ actionName: "getUser" })
  .inputSchema(z.object({ userId: z.string() }))
  .outputSchema(outputSchema)
  .action(async ({ parsedInput }) => {
    const user = await db.user.findUnique({
      where: { id: parsedInput.userId },
    });
    return { id: user.id, name: user.name, email: user.email };
  });
```

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.

| Class                 | Code                    | Expose | Default message             |
| --------------------- | ----------------------- | ------ | --------------------------- |
| `BadRequestError`     | `BAD_REQUEST`           | Yes    | "Bad request"               |
| `ValidationError`     | `VALIDATION_ERROR`      | Yes    | "Invalid input"             |
| `UnauthorizedError`   | `UNAUTHORIZED`          | Yes    | "Unauthorized"              |
| `ForbiddenError`      | `FORBIDDEN`             | Yes    | "Forbidden"                 |
| `NotFoundError`       | `NOT_FOUND`             | Yes    | "Resource not found"        |
| `RateLimitError`      | `RATE_LIMITED`          | Yes    | "Too many requests"         |
| `DatabaseError`       | `DATABASE_ERROR`        | No     | "Database operation failed" |
| `InternalServerError` | `INTERNAL_SERVER_ERROR` | No     | "Something went wrong"      |

## Error Converters

Use helpers when calling better-auth or database APIs that throw.

```ts
// Good: convert external errors into ActionError subclasses
import { fromBetterAuthError } from "@/lib/next-action-handler/error/better-auth-error";
import { toDatabaseError } from "@/lib/next-action-handler/error/database-error";

export function toAuthError(error: unknown) {
  return fromBetterAuthError(error, {
    enumerationSafe: true,
    genericMessage: "Invalid credentials",
  });
}

export function toDbError(error: unknown) {
  return toDatabaseError(error, "Database operation failed");
}
```

## Logging

Logging is automatic. `logActionExecution` runs only when there is no `serverError`. `logActionError` runs for all errors.

## References

- Copy-paste patterns: [references/patterns.md](references/patterns.md)
Files in this package (2)
  • SKILL.md 7 KB
  • references / patterns.md 6 KB

Versions

The database has no other skills named next-action-handler.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version cbd2ea56b178 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95nodejs-logging
    Node.js logging with Winston, Pino, and built-in console. Covers structured logging, log levels, transports, async logging, and production best practices for Express/NestJS applications. USE WHEN: user mentions "node.js logging", "express logging", "nestjs logging", asks about…
  • 100content-sdk-app-router-route-handler-vs-server-action
    Next.js App Router: Server Action vs Route Handler. Server Actions refresh the router, so using one for reads from a client component wipes state in a loading loop. Use when adding an endpoint a client component calls or debugging refreshes.
  • 100pino
    Pino - extremely fast and low overhead Node.js logger with JSON-native structured logging. 10x faster than Winston. Optimized for high-performance APIs and production environments. USE WHEN: user mentions "pino", "fast logging", "high performance logging", "fastify logging",…
  • 100better-auth-authentication
    Better Auth authentication flows for TypeScript apps. Use when enabling email/password auth, configuring social providers, or implementing sign-up, sign-in, and verification flows.
  • 84chatgpt-app-submission
    Use when a developer needs a ChatGPT Apps submission import file from an MCP server. Inspect the implementation, generate chatgpt-app-submission.json with app info, tool-hint justifications, positive and negative test cases, then report review findings and outputSchema warnings.
  • 100better-auth-scaffold
    Scaffolds a Better Auth setup in a Next.js (App Router) + Drizzle project — lib/auth.ts, lib/auth-client.ts, the /api/auth/[...all] route handler, middleware.ts, .env.example, and a permissions module. Produces convention-enforced templates for three plugin presets (minimal,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.