v7 - Rethinking middleware and other updates

[TheEdoRan]

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.

[ludwigbacklund]

I love the amount of thought you've put into this and the desire to make this library even more useful! 💯

Here are my thoughts after reading this and trying out v7 in my own project:

1. Looking at the new API of metadata, schema and define, I would think this is a good opportunity to be able to simplify the case where you don't take any input parameters to your server action. Today you have to use z.void() and then ignore the first parameter when defining the server action like so:

export const someAction = authAction
  .schema(z.void())
  .define(async (_, { ctx: { someContextValue } }) => {
    console.log(someContextValue)
  });

But what if we could instead make schema optional (default it to z.void()?) and commit to the object approach of passing data to server actions so as to not have to ignore the first parameter to define with a _, like so:

export const someAction = authAction
                   // 👇`clientInput` is unknown if you do not call `.schema` before defining the action.
  .define(async ({ clientInput, ctx: { someContextValue } }) => {
    console.log(someContextValue)
  });

This would have the additional benefit of aligning the API of .use and .define where the parameters to them would look the same.

2. I found some bugs with v7. Instead of making issues for each I'll just leave this stackblitz here that shows all of them at once.

[TheEdoRan]

I love the amount of thought you've put into this and the desire to make this library even more useful!

Thank you!

1. But what if we could instead make schema optional (default it to z.void()?)

I think this could be implemented in some way, but I'm not sure defaulting it to z.void() is the proper way to do it, because this library under the hood uses TypeSchema to support multiple validation libraries, and using z.void() would be opinionated. However I agree it's a nice feature, I'll see what I can do about it.

2. I found some bugs with v7

You probably just need to install the TypeSchema adapter for your validation library, in your case: @typeschema/zod. TypeSchema was updated to v0.13 for next-safe-action v7, and since v7 is still in beta, some changes are undocumented; there's no migration guide/blog post yet, but I'll write one before releasing v7 to stable channel. You can find the new installation section in the beta documentation website.

Thank you for your feedback and suggestions!

[TheEdoRan]

Update: renamed define method to action, since it's a better name for what it does. When Form Actions support will land in the library, you'll be able to choose to use action or hookAction method to define a new safe action. hookAction will be stateful (prevState as the first argument of the function), as required by React's useActionState hook.

P.S.: hookAction is not the definitive name, but the most probable one, because stateful actions will be used in conjunction with hooks. Other options are: statefulAction or actionWithState.

[TheEdoRan]

Update: metadata type is now generic in the latest next release and defined using the new defineMetadataSchema optional init function. Updated documentation for metadata can be found here and here.

[Ganyu69]

putting function in one place causing metadata get overwritten

"next-safe-action": "7.0.0-next.23",

[TheEdoRan]

Should be fixed in 7.0.0-next.24. Please let me know, thanks.

[Ganyu69]

@TheEdoRan now actionClient get mutate calling logging middlware twice and auth middleware too

version 7.0.0-next.26

[TheEdoRan]

Yeah, sorry. I accidentally left in a line of code that wasn't supposed to be there while I was testing stuff. Should be fixed in 7.0.0-next.27 (this was due to the clone method removal in 7.0.0-next.25).

[TheEdoRan]

Update: removed clone instance method to extend clients with new middleware function(s). Now use method returns a new safe action client instance with cloned middleware functions from the previous client(s) + the one you just passed to use.

[ludwigbacklund]

Nice to see the simplification of not having to pass a schema to an action if you don't need any parameters 💯 I think a more easily understood API would be not having to call .schema() at all though, rather than having to call it with no parameters. Unless it makes implementation a lot more complex. WDYT?

[TheEdoRan]

I think this is a great suggestion, it makes the API even simpler, which is a very good thing in my opinion. Added support for this feature in 7.0.0-next.28, thank you!

[TheEdoRan]

Update:

• Update React from 14898b6a9 to c3048aab4 vercel/next.js#64798 has been merged, which includes the new useActionState hook, so I'll probably be able to work on Form Actions support soon.

[Ganyu69]

error next.js standalone build. adding @typeschema/zod to serverComponentsExternalPackages still getting same error

Cannot find package '@typeschema/zod' imported from /app/.next/server/chunks/839.js

"next-safe-action": "7.0.0-next.32",
"@typeschema/zod": "^0.13.3",

[TheEdoRan]

Seems to be a TypeSchema issue, but I need a link to a minimal reproduction repo to investigate this. Note that you'll be able to import createSafeActionClient() from /zod path soon, as discussed in #105, this will hopefully solve cases like this one.

[Ganyu69]

v7.0.0-next.36 seems fix my issue