next-action-handler

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.

npm install -D next-action-handler

Usage

From the project root, run the installer:

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.

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

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