Middleware in NestJS

This chapter follows The NestJS request lifecycle.

Nest middleware is Express middleware with dependency injection added. It receives the request, the response, and a next function, and it either calls next() to pass the request on or ends the response itself. Because it runs before routing, it suits work that applies to whole groups of URLs regardless of which handler answers: tagging a request with an ID, setting security headers, or logging that a request arrived.

Class middleware

A class that implements NestMiddleware can inject providers through its constructor, like any other provider:

1
import { Injectable, NestMiddleware } from '@nestjs/common';
2
import { randomUUID } from 'node:crypto';
3
import type { NextFunction, Request, Response } from 'express';
4
import { AppLogger } from '../logging/app-logger';
5

6
@Injectable()
7
export class RequestIdMiddleware implements NestMiddleware {
8
  constructor(private readonly logger: AppLogger) {}
9

10
  use(req: Request, res: Response, next: NextFunction) {
11
    const id = req.header('x-request-id') ?? randomUUID();
12
    req.headers['x-request-id'] = id;
13
    res.setHeader('x-request-id', id);
14
    this.logger.debug(`${req.method} ${req.originalUrl} ${id}`);
15
    next();
16
  }
17
}

A request that never reaches next() and never gets a response hangs until the client times out. Every path through use() must do one or the other.

Function middleware

When middleware has no dependencies, a plain function is enough:

1
import type { NextFunction, Request, Response } from 'express';
2

3
export function noCache(req: Request, res: Response, next: NextFunction) {
4
  res.setHeader('Cache-Control', 'no-store');
5
  next();
6
}

Existing Express middleware packages such as helmet or compression are functions of the same shape and plug in the same way, as long as the app runs on the Express adapter.

Binding middleware to routes

Middleware is not listed in the @Module() decorator. A module implements NestModule and binds middleware in its configure() method through a MiddlewareConsumer:

1
import { MiddlewareConsumer, Module, NestModule, RequestMethod } from '@nestjs/common';
2
import { CatsController } from './cats/cats.controller';
3
import { CatsModule } from './cats/cats.module';
4
import { noCache } from './common/no-cache.middleware';
5
import { RequestIdMiddleware } from './common/request-id.middleware';
6

7
@Module({ imports: [CatsModule] })
8
export class AppModule implements NestModule {
9
  configure(consumer: MiddlewareConsumer) {
10
    consumer.apply(RequestIdMiddleware).forRoutes('{*splat}');
11

12
    consumer
13
      .apply(noCache)
14
      .exclude({ path: 'cats/public', method: RequestMethod.GET })
15
      .forRoutes(CatsController);
16
  }
17
}

forRoutes() accepts path strings, objects with a path and a method, or controller classes, in which case every route of that controller is covered. apply() takes several middleware at once and runs them in the order given. Since NestJS 11 runs on Express 5, wildcards must be named: 'cats/*splat' matches everything below cats/, and '{*splat}' matches every path including the root. Older code with a bare '*' is converted automatically, with a deprecation warning at startup.

Global middleware

app.use() in main.ts binds middleware to every route before any module-bound middleware runs:

1
import helmet from 'helmet';
2

3
const app = await NestFactory.create(AppModule);
4
app.use(helmet());
5
app.enableCors({ origin: ['https://app.example.com'] });

Middleware registered this way is created outside the injector, so it cannot inject providers. For a global middleware that needs a service, use class middleware with forRoutes('{*splat}') in the root module, as in the example above. enableCors() is a built-in shortcut for the CORS middleware.

What middleware should not do

Middleware has no ExecutionContext. It cannot see which handler will run, which decorators that handler carries, or which arguments it takes. That rules it out for some jobs that look like a good fit at first:

Middleware also only exists for HTTP. A GraphQL resolver behind the same server still passes through it, but a microservice message handler or a WebSocket gateway does not. Guards, interceptors, pipes, and filters work in all of them.

Next: Guards in NestJS.