NarixHine/uni-chem / .agents/skills/safe-action-client
safe-action-client
VerifiedUse 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)
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.6 KB |
| client-setup.md | markdown | 4.2 KB |
| error-handling.md | markdown | 4.5 KB |
| input-output-validation.md | markdown | 3.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;
},
});
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |