NarixHine/uni-chem / .agents/skills/safe-action-middleware
safe-action-middleware
VerifiedUse when implementing middleware for next-safe-action -- authentication, authorization, logging, rate limiting, error interception, context extension, or creating standalone reusable middleware with createMiddleware() or createValidatedMiddleware(). Covers both use() (pre-validation) and useValidated() (post-validation) middleware.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.0 KB |
| auth-patterns.md | markdown | 3.2 KB |
| logging-monitoring.md | markdown | 4.0 KB |
| standalone-middleware.md | markdown | 5.4 KB |
logging-monitoring.md
View on GitHub# Logging & Monitoring Middleware
> **Note:** Action files require a `"use server"` directive — omitted from examples below for brevity.
## Request Timing
```ts
export const actionClient = createSafeActionClient().use(
async ({ next, metadata, clientInput }) => {
const start = performance.now();
const result = await next();
const duration = performance.now() - start;
console.log(
`[Action] ${metadata?.actionName ?? "unknown"} completed in ${duration.toFixed(0)}ms`
);
return result;
}
);
```
## Result Inspection
After `await next()`, the result contains the action outcome. Inspect it for logging:
```ts
.use(async ({ next, metadata }) => {
const result = await next();
// result is a discriminated union — exactly one of data / serverError / validationErrors is populated
// (or none, for the idle branch). Checking any one narrows the other two to undefined.
if (result.serverError) {
console.error(`[Action Error] ${metadata?.actionName}:`, result.serverError);
}
if (result.validationErrors) {
console.warn(`[Validation] ${metadata?.actionName}:`, result.validationErrors);
}
return result;
})
```
## Structured Logging
```ts
import { createSafeActionClient } from "next-safe-action";
import { z } from "zod";
import { logger } from "@/lib/logger"; // pino, winston, etc.
export const actionClient = createSafeActionClient({
defineMetadataSchema: () =>
z.object({
actionName: z.string(),
}),
}).use(async ({ next, metadata, clientInput }) => {
const requestId = crypto.randomUUID();
const start = performance.now();
logger.info({
event: "action_start",
action: metadata.actionName,
requestId,
});
const result = await next({ ctx: { requestId } });
const duration = performance.now() - start;
logger.info({
event: "action_complete",
action: metadata.actionName,
requestId,
durationMs: Math.round(duration),
success: !result.serverError && !result.validationErrors,
});
return result;
});
```
## Logging Validated Input
Use `useValidated()` to log the typed, post-validation input — especially useful when schema transforms modify the data:
```ts
// Using actionClient and logger from Structured Logging section above
export const createUser = actionClient
.inputSchema(z.object({ email: z.string().email().transform((e) => e.toLowerCase()) }))
.useValidated(async ({ parsedInput, next, metadata }) => {
logger.info({
event: "validated_input",
action: metadata.actionName,
email: parsedInput.email, // Typed and transformed (lowercased)
});
return next();
})
.action(async ({ parsedInput }) => {
// parsedInput.email is lowercased
});
```
## Error Reporting
Send errors to external monitoring (Sentry, Datadog, etc.):
```ts
import * as Sentry from "@sentry/nextjs";
export const actionClient = createSafeActionClient({
handleServerError: (error) => {
// Report to Sentry
Sentry.captureException(error);
if (error instanceof AppError) {
return error.message;
}
return "An unexpected error occurred.";
},
}).use(async ({ next, metadata }) => {
return Sentry.withScope(async (scope) => {
scope.setTag("action", metadata?.actionName ?? "unknown");
return next();
});
});
```
## Rate Limiting Middleware
```ts
import { headers } from "next/headers";
// Demo only — in-memory maps reset per serverless invocation. Use Redis/Upstash for production.
const rateLimitMap = new Map<string, { count: number; resetAt: number }>();
.use(async ({ next }) => {
const headersList = await headers();
const ip = headersList.get("x-forwarded-for") ?? "unknown";
const now = Date.now();
const limit = rateLimitMap.get(ip);
if (limit && limit.resetAt > now && limit.count >= 10) {
throw new Error("Too many requests. Please try again later.");
}
if (!limit || limit.resetAt <= now) {
rateLimitMap.set(ip, { count: 1, resetAt: now + 60_000 });
} else {
limit.count++;
}
return next();
})
```
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: 196k | 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: 196k | 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: 196k | Updated | Claude CodeCodex | Verified | Install |