Next Compose Middleware

1.0.0 · active · verified Wed Apr 22

next-compose-middleware is a library designed to simplify the creation of complex and declarative middleware for Next.js applications, particularly leveraging Next.js's Edge Runtime middleware. It enables developers to construct highly readable and maintainable middleware logic by composing multiple functions. The current stable version is 2.0.4, indicating active development with incremental releases. Key differentiators include its path-based middleware execution, allowing for "Nested Middleware" behavior, and the ability to compose functions with early exit mechanisms (`breakAll`, `breakOnce`) for fine-grained control over execution flow. This approach helps in organizing middleware into logical, reusable units, enhancing maintainability for applications with intricate authorization, authentication, or request transformation requirements in a single `middleware.ts` file.

Common errors

```
TypeError: next_compose_middleware_1.composeMiddleware is not a function
```
cause Attempting to import `composeMiddleware` using CommonJS `require()` syntax in an ESM context, or an incorrect named import.

fix Ensure you are using ESM `import { composeMiddleware } from 'next-compose-middleware';` syntax, especially in Next.js middleware files which are typically ESM. Verify the symbol name is correct and not a default export.
```
TypeError: Cannot read properties of undefined (reading 'cookies') or 'headers' is undefined
```
cause A middleware function is not returning a valid `NextResponse` object, causing subsequent middleware to receive an undefined or invalid response object.

fix Always ensure your `ComposableMiddleware` functions, especially those implementing early exit logic, explicitly return a `NextResponse` instance (e.g., `return res;`, `return breakAll(res);`, or `return breakOnce(res);`).

Warnings

gotcha This library requires Next.js v12.2.0 or higher for stable middleware support. Older versions of Next.js do not fully support the middleware API that this library leverages, especially regarding nested middleware, which was deprecated in favor of a single root middleware file.
Fix: Upgrade your Next.js project to version 12.2.0 or newer to ensure compatibility and access to stable middleware features.
gotcha Misunderstanding 'breakAll' vs 'breakOnce' in early exit scenarios can lead to unexpected middleware execution flow. 'breakAll' completely halts all subsequent middleware in the entire composition, while 'breakOnce' only stops subsequent middleware at the current nesting level, allowing parent or sibling middleware branches to continue.
Fix: Carefully choose between `breakAll(res)` to completely halt middleware execution or `breakOnce(res)` to only skip siblings in the current path segment, based on your desired control flow.
gotcha Next.js Middleware functions (and thus ComposableMiddleware) run in the Edge Runtime, which has limitations compared to Node.js environments. This means certain Node.js APIs and global objects are unavailable, and environment variables are often resolved at build time, not runtime.
Fix: Avoid Node.js-specific APIs within your middleware. For dynamic environment variables or complex logic, consider using API routes or native Web APIs like `fetch`. Ensure environment variables are configured correctly for the Edge runtime.

Install

npm install next-compose-middleware npm
yarn add next-compose-middleware yarn
pnpm add next-compose-middleware pnpm

Imports

composeMiddleware
wrong:
```
const composeMiddleware = require('next-compose-middleware');
```
correct:
```
import { composeMiddleware } from 'next-compose-middleware';
```
The library is primarily used in Next.js middleware files, which are typically ESM. Avoid CommonJS `require()` syntax.
ComposableMiddleware
```
import type { ComposableMiddleware } from 'next-compose-middleware';
```
This type is used for type-checking custom middleware functions. It should be imported as a type, not a runtime value.

Quickstart

Demonstrates how to set up `next-compose-middleware` with path-based execution for different routes and compose multiple middleware functions, including an example of conditional logic for early exit.

import { NextRequest, NextResponse } from 'next/server';
import { composeMiddleware, ComposableMiddleware } from 'next-compose-middleware';

// Example middleware functions
const root1: ComposableMiddleware = async (req, res) => {
  console.log('Executing root1 for path:', req.nextUrl.pathname);
  // Example: Modify response headers or cookies
  res.headers.set('X-Root-Middleware-1', 'processed');
  return res;
};

const root2: ComposableMiddleware = async (req, res) => {
  console.log('Executing root2 for path:', req.nextUrl.pathname);
  return res;
};

const foo: ComposableMiddleware = async (req, res) => {
  console.log('Executing foo for path:', req.nextUrl.pathname);
  return res;
};

const fooBar: ComposableMiddleware = async (req, res) => {
  console.log('Executing fooBar for path:', req.nextUrl.pathname);
  // Early exit example: if a condition is met, stop further middleware
  if (req.nextUrl.searchParams.has('exit')) {
    console.log('Early exiting from fooBar!');
    return res; // Returning res without breakAll/breakOnce continues chain, but no further changes here.
  }
  return res;
};

const fooId: ComposableMiddleware = async (req, res) => {
  const id = req.nextUrl.pathname.split('/')[2];
  console.log('Executing fooId for path:', req.nextUrl.pathname, 'ID:', id);
  return res;
};

const fooIdBaz: ComposableMiddleware = async (req, res) => {
  console.log('Executing fooIdBaz for path:', req.nextUrl.pathname);
  return res;
};

const fooQux: ComposableMiddleware = async (req, res) => {
  console.log('Executing fooQux for path:', req.nextUrl.pathname);
  return res;
};

export default async function middleware(req: NextRequest) {
  console.log(`\n--- Incoming Request for ${req.nextUrl.pathname} ---`);
  
  // Compose middleware based on paths
  return composeMiddleware(req, NextResponse.next(), {
    scripts: [root1, root2], // Applied to all matching paths
    '/foo': {
      scripts: [foo], // Applied to /foo and its children
      '/bar': {
        scripts: [fooBar], // Applied to /foo/bar and its children
      },
      '/[id]': { // Dynamic segment
        scripts: [fooId], // Applied to /foo/:id and its children
        '/baz': [fooIdBaz] // Applied to /foo/:id/baz
      },
      '/qux': [fooQux] // Applied to /foo/qux
    }
  });
}

view raw JSON →