With nearly 1k stars on GitHub and 10,000 weekly downloads on NPM (thank you!), I finally believe it's time to... rethink how middleware functions work in next-safe-action. My idea is to provide a user experience very similar to the tRPC implementation, which has greatly inspired these changes to the library, so thank you to all the tRPC contributors. This implementation has some differences though, so please keep reading this discussion if you want to know more.

As of version 6, you can pass a single middleware function to createSafeActionClient, which returns a context that will be available to all actions defined with that client, via the serverCode function, as the last argument. This works fine in some cases, but since it's a "monolithic" approach, it's not that powerful and composable, which isn't great.

Let's take a look at the middleware example from the docs, and adapt it to the new implementation. This is how middleware works right now:

import { createSafeActionClient } from "next-safe-action";
import { cookies } from "next/headers";
import { getUserIdFromSessionId } from "./db";

// Base client
export const action = createSafeActionClient();

// Auth client
export const authAction = createSafeActionClient({
  async middleware(parsedInput) {
    const session = cookies().get("session")?.value;

    if (!session) {
      throw new Error("Session not found!");
    }

    const userId = await getUserIdFromSessionId(session);

    if (!userId) {
      throw new Error("Session is not valid!");
    }

    return { userId };
  },
});

First, we're gonna refactor this code using the new middleware implementation, and then I'll discuss about the changes.

import { createSafeActionClient } from "next-safe-action";
import { cookies } from "next/headers";
import { getUserIdFromSessionId } from "./db";

// Base client
const actionClient = createSafeActionClient();

// Auth client
const authActionClient = actionClient.use(async ({ next, ctx }) => {
  const session = cookies().get("session")?.value;

  if (!session) {
    throw new Error("Session not found!");
  }

  const userId = await getUserIdFromSessionId(session);

  if (!userId) {
    throw new Error("Session is not valid!");
  }

  return next({ ctx: { userId } });
});

We can see that we no longer have to pass a middleware function to createSafeActionClient. Instead, we define our middleware functions using use(). The code inside middleware function is almost the same, with just two differences from the previous version:

1. We now get a ctx property as argument of the middleware function, which contains the context value from the previous middleware function.
2. Middleware functions must return the result of the next function, which has useful information about the action execution. Note that the next function expects ctx as argument, that will overwrite the previous value. Context doesn't have to be an object, but if this is the case you can easily include the previous context value by spreading the previous ctx (argument from the middleware) into the new ctx inside next function.

Middleware chaining

The new middleware system is much more powerful than the previous one. You can now await the next middleware function in the stack (useful, for instance, for logging), and chain multiple middleware functions, both at the instance level and at the safe action level. This is very useful when you want to dynamically extend the context and/or halt execution based on your use case.

Middleware at the instance level

Defining middleware at the instance level is useful, for example, when we need to log the result of an action execution, or declare an authActionClient (as above) that verifies if the user intending to execute the operation is authorized to do so, and if not, to halt the execution at that point, by throwing an error. Here we'll redeclare the two safe action clients, defining a logging middleware in the base client and using the authorization one (same as above) in authActionClient. We'll also define a safe action called editProfile, that will use authActionClient. Note that the handleReturnedServerError function passed to the base client will also be used for authActionClient.

// lib/safe-action.ts

import { createSafeActionClient } from "next-safe-action";
import { cookies } from "next/headers";
import { getUserIdFromSessionId } from "./db";

class ActionError extends Error {}

// Base client
const actionClient = createSafeActionClient({
  handleReturnedServerError(e) {
    if (e instanceof ActionError) {
      return e.message;
    }

    return DEFAULT_SERVER_ERROR;
  },
}).use(async ({ next, clientInput, metadata }) => {
  console.log("LOGGING MIDDLEWARE");

  // Here we await the action execution.
  const result = await next({ ctx: null });

  console.log("Result ->", result);
  console.log("Client input ->", clientInput);
  console.log("Metadata ->", metadata);

  return result;
});

// Auth client
const authActionClient = actionClient
  .use(async ({ next }) => {
    const session = cookies().get("session")?.value;

    if (!session) {
      throw new Error("Session not found!");
    }

    const userId = await getUserIdFromSessionId(session);

    if (!userId) {
      throw new Error("Session is not valid!");
    }

    return next({ ctx: { userId } });
  });

"use server";

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

const editProfile = authActionClient
  .metadata({ actionName: "editProfile" }) // we can pass the action name inside `metadata()`
  .schema(z.object({ newUsername: z.string() })) // here we pass the input schema
  .action(async ({ newUsername }, { ctx: { userId } }) => { // here we get `userId` from the middleware defined in `authActionClient`
    await saveNewUsernameInDb(userId, newUsername);

    return {
      updated: true,
    };
  });

Calling editProfile will produce this console output, thanks to the two middleware functions:

LOGGING MIDDLEWARE
Result -> {
  success: true,
  ctx: { userId: 'e473de7f-d1e4-49c1-b4fe-85eb50048b99' },
  data: { updated: true },
  parsedInput: { newUsername: 'johndoe' }
}
Client input -> { newUsername: 'johndoe' }
Metadata -> { actionName: 'editProfile' }

Middleware at the action level

Defining middleware at the Server Action level is useful, for instance, when we want to restrict the execution to specific user roles. In this example we'll use the same authActionClient defined above to define a deleteUser action that chains a middleware function which restricts the execution of this operation to just admins:

"use server";

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

const deleteUser = authActionClient
  .use(async ({ next, ctx }) => {
    const userRole = await getUserRole(ctx.userId); // `userId` comes from the context set in the previous middleware function

    if (userRole !== "admin") {
      throw new ActionError("Only admins can delete users.");
    }
    return next({ ctx }); // here we pass the same context (`userId`) to the next function
  })
  .metadata({ actionName: "deleteUser" })
  .schema(z.void())
  .action(async (_, { ctx: { userId } }) => {
    // Here we're sure that the user that is performing this operation is an admin.
    await deleteUserFromDb(userId);
  });

This is the console output when an admin executes this action:

LOGGING MIDDLEWARE
Result -> {
  success: true,
  ctx: { userId: '9af18417-524e-4f04-9621-b5934b09f2c9' },
  data: null,
  parsedInput: undefined
}
Client input -> undefined
Metadata -> { actionName: 'deleteUser' }

If a regular user tries to do the same, the execution will be stopped at the middleware function that checks the user role, defined at the action level. This is the console output in this case:

LOGGING MIDDLEWARE
Action error: Only admins can delete users. // this line comes from the default `handleServerErrorLog` function
Result -> {
  success: false,
  ctx: { userId: '0a1fa8a8-d323-47c0-bbde-eadbfcdd2587' },
  serverError: 'Only admins can delete users.'
}
Client input -> undefined
Metadata -> { actionName: 'deleteUser' }

Final thoughts

I think this implementation greatly improves the capabilities of the library, since it paves the way for much more complex use cases and code composability, but since this is a fundamental change in how next-safe-action works, I would be very grateful to hear what you, the community, think about these changes. Thank you all for using next-safe-action!

You can find these changes in the middleware-chaining branch. That branch will be merged in next branch when the implementation is finalized and documentation is updated. The new middleware system is expected to land in next-safe-action version 7.