NestJS Middleware Pattern

NestJS Middleware Pattern

Apply NestMiddleware and functional middleware with consumer.forRoutes binding

When to Use

• You need to run logic for every request before routing (logging, rate limiting, correlation ID injection)
• You are integrating Express middleware (e.g., helmet, compression, cors) into a NestJS app
• You need to apply middleware only to specific routes or HTTP methods
• You need request-level context that guards and interceptors cannot provide because it must run before route matching

Instructions

1. Class-based middleware — implements NestMiddleware:

@Injectable()
export class CorrelationIdMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction): void {
    req['correlationId'] = req.headers['x-correlation-id'] ?? randomUUID();
    res.setHeader('X-Correlation-ID', req['correlationId']);
    next();
  }
}

2. Functional middleware — plain function (preferred when no DI needed):

export function requestLogger(req: Request, res: Response, next: NextFunction): void {
  console.log(`${req.method} ${req.url}`);
  next();
}

3. Register in module via configure(consumer: MiddlewareConsumer):

@Module({ controllers: [UsersController] })
export class UsersModule implements NestModule {
  configure(consumer: MiddlewareConsumer): void {
    consumer.apply(CorrelationIdMiddleware).forRoutes(UsersController); // apply to entire controller

    consumer.apply(requestLogger).forRoutes({ path: 'users', method: RequestMethod.GET }); // specific method
  }
}

4. Exclude routes:

consumer
  .apply(AuthMiddleware)
  .exclude({ path: 'auth/login', method: RequestMethod.POST })
  .forRoutes(UsersController);

5. Global Express middleware — apply directly to the Express instance in main.ts (no NestJS wiring needed):

import helmet from 'helmet';
app.use(helmet());
app.use(compression());

6. Chain multiple middleware: .apply(Middleware1, Middleware2).forRoutes(...) — they execute in order.

Details

NestJS middleware is equivalent to Express middleware — it receives (req, res, next) and must call next() or terminate the response. It runs before any NestJS-specific pipeline elements (guards, interceptors, pipes).

Middleware vs Guards: Middleware runs before routing. Guards run after routing with handler/controller metadata available. For authentication, use guards (they have ExecutionContext). For infrastructure concerns (logging, tracing, rate limiting), use middleware.

forRoutes() target types:

• A controller class — applies to all routes in that controller
• A string path — applies to matching URL patterns (supports wildcards)
• A { path, method } object — applies to specific HTTP method + path combinations

Class vs functional: Class middleware can inject providers (e.g., LoggerService, ConfigService) through the constructor. Functional middleware is simpler and slightly faster but cannot use DI. Choose functional when no injection is needed.

Execution order: Middleware declared in a module applies only to routes in that module (unless applied globally via app.use()). Import order in AppModule determines middleware execution order across modules.

Async middleware: Both class and functional middleware can be async. Errors thrown (or passed to next(err)) propagate to NestJS exception filters.

Source

https://docs.nestjs.com/middleware

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.