Docs: improvde documentation on how to write multiple middlewares in a proper manner

[mastoj]

What is the improvement or update you wish to see?

Often when using middleware you might need to use more than one and then chain them, and from the documentation it is not clear how to do it properly. I tried first implementing a chain function like this:

export type MiddlewareFactory = (next: NextMiddleware) => NextMiddleware;
export const chain = (
  middlewareFactories: MiddlewareFactory[],
  index = 0,
): NextMiddleware => {
  const current = middlewareFactories[index];
  if (!current) {
    return () => NextResponse.next();
  }
  const next = chain(middlewareFactories, index + 1);
  return current(next);
};

This was then called in the middleware like such:

export default chain([withSession, withAuth, withInternationalization]);

This was suboptimal in cases where I wanted to use a rewrite or redirect in one middleware and then set some cookies after. I also struggled to set cookies in two different middlewares using a chaining function like this. So ended up created a version that used NextResponse and a context to pass some information between middlewares. So my updated middleware chain function look like this:

export type MiddlewareContext = { [key: string]: unknown };
export type MiddlewareResponse = {
  response: NextResponse<unknown> | undefined;
  context: MiddlewareContext;
};

export type Middleware = (
  request: NextRequest,
  response: NextResponse<unknown> | undefined,
  context: MiddlewareContext,
) => Promise<MiddlewareResponse>;

export const chain =
  (middlewares: Middleware[]): NextMiddleware =>
  async (request: NextRequest, event: NextFetchEvent) => {
    const { response, context } = await middlewares.reduce(
      async (prev: Promise<MiddlewareResponse>, current) => {
        const { response, context } = await prev;
        return current(request, response, context);
      },
      new Promise<MiddlewareResponse>((resolve) =>
        resolve({ context: {}, response: undefined } as MiddlewareResponse),
      ),
    );
    if (response === undefined) {
      return NextResponse.next();
    }
    return response;
  };

This works as intended I think, but it doesn't feel right and some pointers in the documentation would definitely help.

Is there any context that might help us understand?

I think I wrote all that is needed above.

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/app/building-your-application/routing/middleware

[stefanprobst]

@samcx this is not about multiple middleware files, but about multiple middleware functions - and the documentation about combining multiple middleware functions (merge headers etc.) is still rather sparse.

[stefanprobst]

@samcx

This isn't a pattern we support with Middleware at the moment

are you saying that e.g. using the middleware provided by next-intl (for i18n) and the middleware provided by next-auth (for auth) in the same next.js project is not a supported pattern?

[samcx]

in the same next.js project is not a supported pattern?

@stefanprobst No—I see what you mean though, let me remove my previous the post to prevent confusion.

I think it really depends how these wrappers are built, for e.g., it seems more possible to chain wrappers with next-auth → https://next-auth.js.org/configuration/nextjs#wrap-middleware (there is a Middleware function), but I'm more confused how to do the same with next-intl → https://next-intl.dev/docs/getting-started/app-router/with-i18n-routing#middleware. You could probably wrap createMiddleware() around the Middleware function if you wanted to combine both of these.

I don't think our documentation is the right place for this, since it would depend on these packages.

[samcx]

Nevermind, there is documentation for this with next-intl → https://next-intl.dev/docs/routing/middleware#composing-other-middlewares.

[stefanprobst]

i think it's a common enough problem that the next.js docs should provide some high-level guidance on how to compose these middleware functions.

[mastoj]

I agree with @stefanprobst. My point wasn't about it having multiple files, more about recommended structure. In all other frameworks that has middleware there is always a story around composition, and it would be good to have clear documentation on how to do it in a performant and structured way.

[samcx]

frameworks that has middleware there is always a story around composition

@mastoj Can you point to other framework's documentation where as examples? 👀

[mastoj]

@samcx Sure.

express: https://expressjs.com/en/guide/using-middleware.html
dotnet: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/middleware/?view=aspnetcore-9.0
laravel: https://laravel.com/docs/11.x/middleware

If you look at functional approaches there are things like giraffe where basically everything is a middleware that you compose together: https://giraffe.wiki/docs#httphandler

I definitely understand that there are some limitations at the moment, but the concept of chaining together different middleware components is not something new and sort of expected for a middleware concept I would say. Since the design of middleware in next is not focused on it I think some guidance in documentation around recommended approach would be good.

[samcx]

@mastoj

express: https://expressjs.com/en/guide/using-middleware.html

This is not an apples to apples comparison. Middleware in Express (a key detail being this is a Node.js Server) is designed to be nestable, etc. This is possible when this all lives in a single Express app/Node.js server. Middleware in Next.js is not a Node.js server—it is a separate, lightweight layer that can run on every path in your app, on every request, before the application path is served.

(quoting from the Next.js docs)

Heavy Computational Tasks: Middleware should be lightweight and respond quickly or it can cause delays in page load. Heavy computational tasks or long-running processes should be done within dedicated Route Handlers.

• https://nextjs.org/docs/app/building-your-application/routing/middleware
• https://vercel.com/docs/functions/edge-middleware

Limitations with the runtime (e.g., Edge Runtime, but Node.js Runtime is coming soon!, code size limit, etc.), and design of Middleware were intentional so there is minimal latency of running your Middleware before serving your application.

So, as it stands today, Next.js Middleware is just a simple export default function middleware(). So there isn't really "guidance" for us to share on how to do this the right way, since it is just simply composing JavaScript logic. How these dependencies what to integrate their logic in Middleware is up to them. I see next-intl actually provides an example here when combined with next-auth → https://next-intl.dev/docs/routing/middleware#example-auth-js.

• https://nextjs.org/docs/app/building-your-application/routing/middleware#convention

[github-actions]

This closed issue has been automatically locked because it had no new activity for 2 weeks. If you are running into a similar issue, please create a new issue with the steps to reproduce. Thank you.