Skip to content

NarixHine/uni-chem / .agents/skills/safe-action-client

safe-action-client

Verified

Use when creating or configuring a next-safe-action client, defining actions with input/output validation, handling server errors, or setting up createSafeActionClient with Standard Schema (Zod, Yup, Valibot)

FileKindSize
SKILL.mdskill md4.6 KB
client-setup.mdmarkdown4.2 KB
error-handling.mdmarkdown4.5 KB
input-output-validation.mdmarkdown3.1 KB

client-setup.md

View on GitHub
# Client Setup & Configuration

## createSafeActionClient Options

```ts
import { createSafeActionClient } from "next-safe-action";
import { z } from "zod";

export const actionClient = createSafeActionClient({
  // Optional: define a metadata schema (actions must call .metadata() before .action())
  defineMetadataSchema: () =>
    z.object({
      actionName: z.string(),
    }),

  // Optional: customize how server errors are handled
  // handleServerError receives (error, utils) where utils has: clientInput, bindArgsClientInputs, ctx, metadata
  handleServerError: (error, utils) => {
    // Log the error server-side with context
    console.error("Action error:", error.message, { metadata: utils.metadata });
    // Return a user-facing message (this becomes result.serverError)
    return "Something went wrong. Please try again.";
  },

  // Optional: set default validation error shape for all actions
  // "formatted" (default) = nested { _errors: string[] }
  // "flattened" = { formErrors: string[], fieldErrors: { [field]: string[] } }
  defaultValidationErrorsShape: "formatted",

  // Optional: throw validation errors instead of returning them
  throwValidationErrors: false,
});
```

## Layered Clients Pattern

Build specialized clients by extending a base client with middleware:

```ts
// src/lib/safe-action.ts
import { createSafeActionClient } from "next-safe-action";

// Base client — no auth required
export const actionClient = createSafeActionClient({
  handleServerError: (error) => {
    console.error("Action error:", error.message);
    return error.message;
  },
});

// Auth client — requires authenticated session
export const authActionClient = actionClient.use(async ({ next }) => {
  const session = await getSession();
  if (!session?.user) {
    throw new Error("Unauthorized");
  }
  return next({
    ctx: { userId: session.user.id, userRole: session.user.role },
  });
});

// Admin client — requires admin role
export const adminActionClient = authActionClient.use(async ({ next, ctx }) => {
  if (ctx.userRole !== "admin") {
    throw new Error("Forbidden");
  }
  return next({ ctx });
});
```

Then use the appropriate client per action:

```ts
"use server";

import { z } from "zod";
import { actionClient, authActionClient, adminActionClient } from "@/lib/safe-action";

// Public action — no auth needed
export const getPublicData = actionClient.action(async () => {
  return { data: "public" };
});

// Authenticated action — session required
export const getUserProfile = authActionClient.action(async ({ ctx }) => {
  const profile = await db.user.findById(ctx.userId);
  return profile;
});

// Admin action — admin role required
export const deleteUser = adminActionClient
  .inputSchema(z.object({ targetUserId: z.string().uuid() }))
  .action(async ({ parsedInput, ctx }) => {
    await db.user.delete(parsedInput.targetUserId);
    return { deleted: true };
  });
```

## Custom Server Error Type

By default, `serverError` is a `string`. For structured errors:

```ts
class AppError extends Error {
  constructor(
    message: string,
    public code: string,
    public statusCode: number
  ) {
    super(message);
  }
}

const actionClient = createSafeActionClient({
  handleServerError: (error) => {
    if (error instanceof AppError) {
      return {
        message: error.message,
        code: error.code,
        statusCode: error.statusCode,
      };
    }
    return {
      message: "An unexpected error occurred",
      code: "INTERNAL_ERROR",
      statusCode: 500,
    };
  },
});
```

The return type of `handleServerError` determines the `ServerError` generic throughout the entire client chain.

## DEFAULT_SERVER_ERROR_MESSAGE

When `handleServerError` is not provided, any non-Error throws produce this default message:

```ts
import { DEFAULT_SERVER_ERROR_MESSAGE } from "next-safe-action";
// Value: "Something went wrong while executing the operation."
```

You can use this constant in your own `handleServerError` as a fallback:

```ts
import { DEFAULT_SERVER_ERROR_MESSAGE } from "next-safe-action";

const actionClient = createSafeActionClient({
  handleServerError: (error) => {
    if (error instanceof AppError) {
      return error.message;
    }
    return DEFAULT_SERVER_ERROR_MESSAGE;
  },
});
```
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall