Express-Like Middleware in Next.js API Route Handler

Next.js is an incredible framework. I mean it’s packed with server-side rendering (SSR), static site generation (SSG), API routes and powerful optimizations that make it one of the best choices for modern web development.

But if you're coming from an Express.js background, especially when working with Nextjs API Route handlers, you might feel something’s missing - Middleware.

In Express.js, middleware is at the core of request handling. It allows you to inject authentication, validation, logging, and other reusable logic before a request reaches the actual route handler. The traditional req, res, next flow makes it easy to chain multiple middleware functions together, ensuring every request passes through a structured pipeline.

Next.js does provide middleware, but it works differently. Instead of the traditional Express-style approach, Next.js middleware runs at the edge before a request reaches a specific API route or page. This is called Edge Middleware and it operates at the CDN level, allowing you to modify requests and responses before they hit your application. It’s highly performant and ideal for tasks like auth redirects, A/B testing, internationalization and so on.

However, Edge Middleware has some limitations; it doesn’t have access to request bodies, and you can’t use traditional Node.js APIs like fs or database queries. This means if you’re looking to implement middleware inside API routes in a way that feels like Express, you need a different approach.

So, how do we bring back the flexibility of Express-like middleware inside Next.js API routes, while keeping it type-safe and developer-friendly?

In this article, I'll show you how I built a flexible, type-safe middleware pattern for Next.js that brings back the best parts of Express without compromising Next.js’s strengths. If you’ve ever wished Next.js middleware worked more like Express, this is for you! 🚀

The Core Components

Our implementation consists of three main parts:

• Middleware handler

• Middleware functions

• Route handlers that use these middlewares

The Middleware Handler

First, let's look at our core middleware handler that orchestrates the middleware execution:

handler.ts

export const handler: Handler = (...middleware) => async (request, params) => {
  const result = await execMiddleware(middleware, request, params);
  if (result) {
    return result;
  }
  return ErrorResponse('Your handler or middleware must return a NextResponse!', 400);
};

Code Explanation

This handler:

• Takes an array of middleware functions and the original handler function, then executes them in sequence

• It allows each middleware to either pass control to the next middleware or return a response

• At the end of the execution, If no response is returned, it sends an error response.

Now, let’s break down the execMiddleware function, which does the heavy lifting:

const execMiddleware: ExecMiddleware = async (middleware, request, params) => {
  for (const middlewareFn of middleware) {
    let nextInvoked = false;
    const next = async () => {
      nextInvoked = true;
    };
    const result = await middlewareFn(request, params, next);
    if (!nextInvoked) {
      return result;
    }
  }
};

Code Explanation

Iterating Over Middleware Functions:

• We loop through the array of middleware functions (for (const middlewareFn of middleware)).

The next Function:

• Each middleware receives a next function it can call to pass control to the next middleware in the sequence.

• We use let nextInvoked = false; to track whether next() was actually called.

Handling Middleware Execution:

• We await the middleware function, allowing it to process the request.

• If next() was not called, we assume the middleware returned a response, and we stop execution.

This pattern allows us to chain multiple middleware functions together seamlessly just like in Express.js.

Now, let’s define our middleware functions and see how to apply them in Next.js API routes.

Authentication Middleware

Here's an example of how we implement authentication middleware:

protect.ts

export const protect: AuthorizeUser = async (req, params, next) => {
  let token = '';
  const authorization = req.headers.get('authorization');
  const cookie = req.cookies.get('auth')?.value;

  if (!authorization && !cookie) {
    return ErrorResponse('You are not logged in. Please log in to get access', 401);
  }

  if (authorization && authorization.startsWith('Bearer')) 
    token = authorization.split(' ')[1];

  if (cookie) 
    token = cookie;

  try {
    const user = (await verifyToken(token, process.env.JWT_SECRET!)) as User;
    if (!isEmpty(user)) 
      req.user = user;
  } catch (error) {
    return handleTokenError(error);
  }

  if (isEmpty(req.user)) {
    return ErrorResponse('Not authorized to access this route', 401);
  }

  next();
};

Looks familiar? That's because it's almost identical to project middlewares in Express.js!

Code Explanation:

This middleware ensures that only authenticated users can access protected routes.

1. Extract Token:

   • It first checks if an authentication token is provided either in:

     • The Authorization header (Bearer <token>)

     • The auth cookie.

   • If no token is found, it returns a 401 Unauthorized error.

2. Verify Token:

   • If the token exists, it verifies it using verifyToken(token, process.env.JWT_SECRET!).

   • If the token is valid, it extracts the user information and attaches it to req.user.

3. Handle Errors:

   • If an error occurs (invalid or expired token), it calls handleTokenError(error).

   • If no valid user is found, it returns a 401 Unauthorized error.

4. Proceed to Next Middleware:

   • If authentication succeeds, it calls next() to allow access to the next middleware or the handler itself if no other middleware.

Role-Based Authorization

We also implemented a flexible role-based authorization middleware:

authorize.ts

export const authorize: AuthorizeRoles = (...roles) => {
  return async (req, params, next) => {
    if (!roles.includes(req.user.role)) 
      return ErrorResponse('Forbidden: Access denied', 401);
    next();
  };
};

Code Explanation:

This middleware restricts access based on user roles.

1. Receives a List of Allowed Roles:

   • It takes an array of roles (e.g., 'ADMIN', 'USER').

2. Checks User Role:

   • If req.user.role is not included in the allowed roles, it returns a 401 Forbidden error.

3. Allows Access If Authorized:

   • If the user has a valid role, it calls next() to proceed to the next middleware or the handler itself if no other middleware.

Using the Middleware in Routes

Now that we have our middleware functions, let's see how to apply them in Next.js API routes.

user/route.ts

// Example protected route
const handleGetLoggedinUser = asyncHandler(async (req: CustomRequest) => {
  const user = await prisma.user.findUnique({ 
    where: { id: req.user.id } 
  });

  return ApiResponse(user);
});

const GET = handler(protect, handleGetLoggedinUser);

Explanation:

1. handleGetLoggedinUser (Protected Route)

   • Retrieves the currently logged-in user from the database.

2. Route Middleware Handling

• GET /user → Uses protect middleware to ensure the request is authenticated,.

user/[id]/route.ts

// Example authorized route
const handleDeleteUser = asyncHandler(async (req: CustomRequest, params: { id: string }) => {
  const { id } = params;
  const user = await prisma.user.findUnique({ where: { id } });
  if (!user) {
    return ErrorResponse('User not found', 404);
  }
  await prisma.user.delete({ where: { id } });
  return ApiResponse(null, 'User deleted successfully');
});



const DELETE = handler(protect, authorize('ADMIN'), handleDeleteUser);

export { GET, DELETE };

Explanation:

1. handleDeleteUser (Role-Restricted Route)

   • Deletes a user based on the provided id.

2. Route Middleware Handling

   • DELETE /user/:id → Uses both protect and authorize('ADMIN'), ensuring the request is first authenticated and only admin users can delete user accounts.

Example Usage with Request Body Validation

Before processing requests, let's validate incoming data using a request body validation middleware.

auth.validation.ts

const signUpSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

export const validateSignupBody: ValidateCreateUser = async (req, params, next) => {
  const data = await req.clone().json();
  const response = signUpSchema.safeParse(data) as ValidateParseResponse;
  if (!response.success) {
    const { errors } = response.error;
    const errorMessage = generateErrorMessage(errors, options);
    return ErrorResponse(errorMessage, 422);
    }
  next();
};

Code Explanation:

This middleware validates request data before processing the signup request.

1. Defines a Schema (signUpSchema)

   • Uses zod to define a validation schema for signup data:

     • email must be a valid email.

     • password must have at least 8 characters.

2. Validates Incoming Request Data

   • Extracts JSON data from the request.

   • Uses safeParse(data) to validate the request body.

3. Handles Validation Errors

   • If validation fails, it generates an error message and returns a 422 Unprocessable Entity error.

4. Proceeds to Next Middleware

   • If validation passes, it calls next() function.

Validation Middleware Usage in Routes

Now, let's put our validation middleware into action by before calling the handler itself.

signup.ts

const handleSignup = asyncHandler(async (req: CustomRequest) => {
  const { email, password } = await req.json();

  const hashedPassword = await bcrypt.hash(password, 10);

  const user = await prisma.user.create({ 
    data: { email, password: hashedPassword } 
  });

  return ApiResponse(user);
});

const POST = handler(validateSignupBody, handleSignup);

export { POST };

Explanation:

1. Handles User Signup (handleSignup)

   • Extracts email and password from the request body.

   • Hashes the password using bcrypt before storing it in the database.

   • Saves the new user using Prisma ORM.

2. Uses validateSignupBody Middleware

   • Ensures the request body is valid before calling handleSignup.

Async Handler Function

Finally, let’s make sure our API rock-solid by handling errors the right way. Instead of letting unexpected issues crash our app, we’ll wrap our route handlers in a smart async function that catches and processes errors gracefully.

async-handler.ts

export const asyncHandler = <T extends ObjectData>(handler: AsyncHandler<T>) => {
  return async (req: CustomRequest, params?: { params: Promise<T> }) => {
    try {
      const resolvedParams = (await params?.params) ?? ({} as T);
      const resp = await handler(req, resolvedParams);
      return resp;
    } catch (error) {
      if (error?.isApiException) {
        const { message, statusCode, data } = error;
        return ErrorResponse(message, statusCode, data);
      } else if ( error instanceof PrismaClientKnownRequestError || error instanceof PrismaClientValidationError) {
        // Return Custom error here: e.g db-related errors
        return handlePrismaError(error);
      } else {
        return ErrorResponse('Internal Server Error', 500);
      }
    }
  };
};

Explanation:

This helper function handles errors in async functions to prevent unhandled promise rejections.

1. Executes the Route Handler (handler)

   • Wraps the request processing logic in a try-catch block.

2. Handles Known Errors:

   • If an API exception occurs, it returns an error response.

   • If a Prisma ORM error occurs, it calls handlePrismaError(error).

   • Otherwise, it returns a 500 Internal Server Error.

Conclusion

And there you have it. And there you have it! 🎉 We’ve devised a simple yet effective way to implement Express-like middleware in a Next.js app - without fighting against the framework. While there are always ways to refine and optimize, this approach keeps things clean, modular, and easy to extend.

Curious to see the full code or experiment with it yourself? Check out the GitHub repository GitHub repository 🚀 Happy coding!