nextjs-multi-middleware

Brings Express-style middleware chaining to Next.js.

This utility lets you chain multiple middleware functions, using path-to-regexp for route matching. It's a simple way to organize your middleware logic into clean, reusable functions.

If a middleware in the chain returns a NextResponse, the chain halts and the response is sent. Otherwise, the chain continues to the next middleware.

Why nextjs-multi-middleware?

In complex Next.js applications, a single middleware file can become bloated with conditional logic for different routes. nextjs-multi-middleware solves this by allowing you to split your logic into independent, composable middleware functions, each with its own route matching. This leads to cleaner, more maintainable code.

It is also lightweight, has zero dependencies, and is fully compatible with the Vercel Edge Runtime.

Installation

npm install nextjs-multi-middleware

or

yarn add nextjs-multi-middleware

Usage Example

Here’s how to use nextjs-multi-middleware in your middleware.ts file.

// middleware.ts
import { NextResponse, NextRequest, NextFetchEvent } from 'next/server';
import { chain, Middleware, ErrorMiddleware, NextMiddlewareMulti, StandardNextMiddleware } from 'nextjs-multi-middleware';

// 1. Define your middlewares

// A simple logger
const loggingMiddleware = (req: NextRequest) => {
  console.log(`Request to: ${req.nextUrl.pathname}`);
};

// Auth middleware with a specific matcher
const authMiddleware = (req: NextRequest) => {
  const isAuthenticated = req.cookies.get('session_token')?.value;
  if (!isAuthenticated) {
    return NextResponse.redirect(new URL('/login', req.url));
  }
  return NextResponse.next();
};

// A middleware that might throw an error
const riskyMiddleware = async (req: NextRequest) => {
  if (req.nextUrl.pathname.startsWith('/api/risky')) {
    throw new Error('This is a simulated error!');
  }
};

// An error handler (must have 4 arguments)
const errorHandler: ErrorMiddleware = async (error, req, event, next) => {
  console.error('Caught error in middleware chain:', error.message);
  return new NextResponse(
    JSON.stringify({ success: false, message: 'An internal error occurred.' }),
    { status: 500, headers: { 'content-type': 'application/json' } }
  );
};

// 2. Configure the chain
const allMiddlewares: Middleware[] = [
  loggingMiddleware, // Runs on all paths
  {
    handler: authMiddleware,
    matcher: '/admin/:path*', // Uses path-to-regexp
  },
  riskyMiddleware,
  // Error handlers should be last
  errorHandler,
];

// 3. Export the chain (debug mode is optional)
export default chain(allMiddlewares, { debug: true });

// 4. Define the global matcher for Next.js
export const config = {
  matcher: ['/admin/:path*', '/api/:path*', '/((?!_next/static|favicon.ico).*)'],
};

Features

• Execution Order: Middlewares run in the order they are defined. If a middleware returns a NextResponse, the chain stops.
• Flexible API: Pass an array of raw functions or MiddlewareConfig objects ({ handler, matcher }) to the chain function.
• Route Matching: Use path-to-regexp strings (/users/:id) or a predicate function (req: NextRequest) => boolean for fine-grained control. If no matcher is provided, the middleware runs on all requests.
• Error Handling: Create middleware with four arguments (error, req, event, next) to catch errors from preceding middlewares.
• Debug Mode: Pass { debug: true } to chain to log the execution flow and matcher results.

export default chain(allMiddlewares, { debug: true });

Recipes

Here are a few recipes for common use cases.

Recipe: Passing Data Between Middlewares

Since middleware functions don't share a direct context object, the recommended way to pass data is by modifying request headers. The next() callback in custom middlewares can accept a new NextRequest object to pass it down the chain.

// 1. First middleware adds data to headers
const addUserToHeaders: NextMiddlewareMulti = async (req, event, next) => {
  // In a real app, you'd get this from a session or token
  const user = { id: '123', role: 'admin' };

  // Clone the request headers and set a new header
  const headers = new Headers(req.headers);
  headers.set('x-user-info', JSON.stringify(user));

  // Create a new request with the new headers
  const newReq = new NextRequest(req.url, {
    headers,
    // It's important to pass the original request object to keep its properties
    request: req,
  });

  // Pass the modified request to the next middleware
  return await next(newReq, event);
};

// 2. A later middleware or API route can read it
const anotherMiddleware = (req: NextRequest) => {
  const userHeader = req.headers.get('x-user-info');
  if (userHeader) {
    const user = JSON.parse(userHeader);
    console.log('User found in headers:', user); // { id: '123', role: 'admin' }
  }
};

Recipe: A/B Testing with Cookies

Middleware is perfect for A/B testing by rewriting paths based on cookies.

const abTestMiddleware: StandardNextMiddleware = (req) => {
  const bucket = req.cookies.get('ab-bucket')?.value;
  const url = req.nextUrl;

  if (bucket === 'new-design' && url.pathname === '/products') {
    // Rewrite to the new page variant
    url.pathname = '/products-new';
    return NextResponse.rewrite(url);
  }

  // Otherwise, continue to the default page
};

License

MIT