Loading...
Loading...
Use 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.
npx skill4agent add next-safe-action/skills safe-action-middlewareimport { createSafeActionClient } from "next-safe-action";
const actionClient = createSafeActionClient();
// Add middleware with .use()
const authClient = actionClient.use(async ({ next }) => {
const session = await getSession();
if (!session?.user) {
throw new Error("Unauthorized");
}
// Pass context to the next middleware/action via next({ ctx })
return next({
ctx: { userId: session.user.id },
});
});.use().use()next({ ctx })const client = createSafeActionClient()
.use(async ({ next }) => {
console.log("1: before"); // Runs 1st
const result = await next({ ctx: { a: 1 } });
console.log("1: after"); // Runs 4th
return result;
})
.use(async ({ next, ctx }) => {
console.log("2: before", ctx.a); // Runs 2nd, ctx.a = 1
const result = await next({ ctx: { b: 2 } });
console.log("2: after"); // Runs 3rd
return result;
});
// In .action(): ctx = { a: 1, b: 2 }async ({
clientInput, // Raw input from the client (unknown)
bindArgsClientInputs, // Raw bind args array
ctx, // Accumulated context from previous middleware
metadata, // Metadata set via .metadata()
next, // Call to proceed to next middleware/action
}) => {
// Optionally extend context
return next({ ctx: { /* new context properties */ } });
}.useValidated()parsedInputuse()useValidated()const action = authClient
.inputSchema(z.object({ postId: z.string().uuid(), title: z.string() }))
.useValidated(async ({ parsedInput, ctx, next }) => {
// parsedInput is typed: { postId: string; title: string }
const post = await db.post.findById(parsedInput.postId);
if (!post || post.authorId !== ctx.userId) {
throw new Error("Not authorized");
}
return next({ ctx: { post } });
})
.action(async ({ parsedInput, ctx }) => {
// ctx.post is available and typed
await db.post.update(ctx.post.id, { title: parsedInput.title });
});1. use() middleware — pre-validation, runs in order added
2. Input validation — schema parsing
3. useValidated() middleware — post-validation, runs in order added
4. Server code (.action()) — receives final ctx and parsedInputnext()next()| Need | Method |
|---|---|
| Authentication, logging, rate limiting (no input needed) | |
Access to raw | |
| Authorization based on validated input (e.g., check user owns resource) | |
| Logging or auditing validated/transformed input | |
| Enriching context with data derived from parsed input | |
async ({
parsedInput, // Validated, typed input (from inputSchema)
clientInput, // Raw input from the client
bindArgsParsedInputs, // Validated bind args tuple
bindArgsClientInputs, // Raw bind args array
ctx, // Accumulated context from all previous middleware
metadata, // Metadata set via .metadata()
next, // Call to proceed to next middleware/action
}) => {
return next({ ctx: { /* new context properties */ } });
}.inputSchema().bindArgsSchemas().useValidated().inputSchema().bindArgsSchemas().useValidated().use().useValidated().useValidated()useValidated()parsedInputclientInputauthClient
.inputSchema(z.string().transform((s) => s.toUpperCase()))
.useValidated(async ({ clientInput, parsedInput, next }) => {
console.log(clientInput); // "hello" (original)
console.log(parsedInput); // "HELLO" (transformed)
return next();
})use()onErroronSettleduseValidated()undefineduseValidated()// BAD: Forgetting to return next() — action will hang
.use(async ({ next }) => {
await doSomething();
next({ ctx: {} }); // Missing return!
})
// GOOD: Always return the result of next()
.use(async ({ next }) => {
await doSomething();
return next({ ctx: {} });
})// BAD: Catching all errors (swallows framework errors like redirect/notFound)
.use(async ({ next }) => {
try {
return await next({ ctx: {} });
} catch (error) {
return { serverError: "Something went wrong" }; // Swallows redirect!
}
})
// GOOD: Re-throw framework errors
.use(async ({ next }) => {
try {
return await next({ ctx: {} });
} catch (error) {
if (error instanceof Error && "digest" in error) {
throw error; // Let Next.js handle redirects, notFound, etc.
}
// Handle other errors
console.error(error);
return { serverError: "Something went wrong" };
}
})// BAD: useValidated() without an input schema — won't compile
const client = actionClient.useValidated(async ({ parsedInput, next }) => {
return next();
});
// GOOD: Always define inputSchema or bindArgsSchemas before useValidated()
const client = actionClient
.inputSchema(z.object({ id: z.string() }))
.useValidated(async ({ parsedInput, next }) => {
console.log(parsedInput.id); // Typed!
return next();
});