Next Middleware Chain

A fluent, composable middleware chain builder for Next.js. Chain built-in and custom middleware together with a clean builder API.

Installation

npm install next-mw-chain

Quick Start

// proxy.ts or middleware.ts
import { middlewareChain, type MiddlewareFactory } from "next-mw-chain";
import { NextResponse } from "next/server";
import { myApi } from "@/lib/api";

// custom middleware
const authMiddleware: MiddlewareFactory = (next) => async (req, event, res) => {
  const token = req.cookies.get("accessToken")?.value;
  if (!token) return NextResponse.redirect(new URL("/login", req.url));
  return next(req, event, res);
};

export default middlewareChain()
  .refresh({ refreshFn: (token) => myApi.refresh(token) })
  .use(authMiddleware)
  .build();

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};

Built-in Middleware

.refresh(config)

Automatically refreshes an expired JWT access token using a refresh token. On success it sets fresh cookies and continues the request. On failure it clears both cookies and redirects to the login page.

middlewareChain()
  .refresh({
    refreshFn: async (refreshToken) => {
      const res = await fetch("https://your-api.com/auth/refresh", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ refreshToken }),
      });
      if (!res.ok) return null;
      return res.json(); // must return { accessToken, refreshToken }
    },
  })
  .build();

RefreshTokenConfig

Option	Type	Default	Description
refreshFn	(token: string) => Promise<{ accessToken?: string; refreshToken?: string } | null>	—	Required. Calls your API and returns new tokens
loginPath	string	"/login"	Redirect target when refresh fails
cookieNames	{ accessToken?: string; refreshToken?: string }	{ accessToken, refreshToken }	Override cookie names if yours differ
cookieOptions	{ maxAge?, sameSite?, secure?, httpOnly? }	{ httpOnly, secure, lax, 7d }	Options applied to both cookies when setting
isExpired	(exp?: number) => boolean	Compares exp * 1000 to Date.now()	Override the default expiry check

With all options:

middlewareChain()
  .refresh({
    refreshFn: (token) => myApi.refresh(token),
    loginPath: "/auth/login",
    cookieNames: {
      accessToken: "access_token",
      refreshToken: "refresh_token",
    },
    cookieOptions: {
      httpOnly: true,
      secure: true,
      sameSite: "lax",
      maxAge: 60 * 60 * 24 * 7, // 7 days
    },
    isExpired: (exp) => !exp || Date.now() >= exp * 1000,
  })
  .build();

Note: Always place .refresh() before your auth middleware so the token is fresh by the time the auth check runs.

---

.use(factory)

Register any custom middleware. This is the primary way to add auth, CSRF protection, CORS, maintenance mode, or any other app-specific logic.

const myMiddleware: MiddlewareFactory = (next) => async (req, event, res) => {
  // do something before
  const result = await next(req, event, res);
  // do something after
  return result;
};

middlewareChain().use(myMiddleware).build();

---

Custom Middleware

Every middleware is a MiddlewareFactory — a function that receives the next handler and returns a new handler. Import the type to get full TypeScript support.

import type { MiddlewareFactory } from "next-mw-chain";
import { NextResponse } from "next/server";

const corsMiddleware: MiddlewareFactory = (next) => async (req, event, res) => {
  if (!req.nextUrl.pathname.startsWith("/api")) {
    return next(req, event, res);
  }

  const result = await next(req, event, res);
  const response = result ?? NextResponse.next();

  response.headers.set("Access-Control-Allow-Origin", "*");
  response.headers.set(
    "Access-Control-Allow-Methods",
    "GET,POST,PUT,DELETE,OPTIONS",
  );
  response.headers.set(
    "Access-Control-Allow-Headers",
    "Content-Type, Authorization",
  );

  if (req.method === "OPTIONS") {
    return new NextResponse(null, { status: 204, headers: response.headers });
  }

  return response;
};

---

API Reference

middlewareChain()

Returns a MiddlewareBuilder instance. Chain methods then call .build() to produce the Next.js middleware function.

MiddlewareBuilder

| Method | Description | | ------------------- | --------------------------------------------------- | | | .refresh(config?) | Add refresh token middleware | | .use(factory) | Add any custom MiddlewareFactory | | .build() | Finalise and return the Next.js middleware function |

chain(factories)

Low-level function that composes an array of MiddlewareFactory functions into a single handler. Use this if you prefer to skip the builder.

Types

// A middleware function
type MiddlewareHandler = (
  request: NextRequest,
  event: NextFetchEvent,
  response: NextResponse,
) => NextMiddlewareResult | Promise<NextMiddlewareResult>;

// A factory that wraps a handler and returns a new handler
type MiddlewareFactory = (next: MiddlewareHandler) => MiddlewareHandler;

---

Requirements

• Node.js 18+
• Next.js 15+
• TypeScript 5+ (TypeScript 6 recommended)

License

MIT © SOUM SOMON