Functional middleware in NestJS - Deep Dive

Overview - Functional middleware

What is it?

Functional middleware in NestJS is a simple function that runs during the request-response cycle. It can read or modify the request and response objects before passing control to the next function. This helps add features like logging, authentication, or error handling without changing the main code.

Why it matters

Without middleware, every route handler would need to repeat common tasks like checking user login or logging requests. Functional middleware lets you write these tasks once and reuse them everywhere, making your code cleaner and easier to maintain. It also helps keep your app organized and scalable.

Where it fits

Before learning functional middleware, you should understand basic NestJS concepts like modules, controllers, and providers. After mastering middleware, you can explore advanced topics like interceptors, guards, and exception filters to control request flow and security.

Mental Model

Core Idea

Functional middleware is a simple function that intercepts requests to add or change behavior before reaching the main handler.

Think of it like...

It's like a security guard at a building entrance who checks visitors before letting them inside. The guard can stop, allow, or modify the visitor's path based on rules.

┌───────────────┐   request   ┌───────────────┐   next()   ┌───────────────┐
│ Client       │────────────▶│ Middleware    │───────────▶│ Controller    │
└───────────────┘            └───────────────┘           └───────────────┘

Middleware can:
- Read or change request
- Perform tasks (e.g., logging)
- Call next() to continue
- Or end response early

Build-Up - 7 Steps

1

Foundation

Understanding Middleware Basics

Concept: Middleware is a function that runs between receiving a request and sending a response.

In NestJS, middleware functions take three arguments: request, response, and next. They can read or modify the request or response objects. Calling next() passes control to the next middleware or route handler.

Result

You can add code that runs for every request, like logging or checking headers.

Understanding middleware as a simple function clarifies how you can insert custom logic anywhere in the request flow.

2

Foundation

Creating a Functional Middleware

Concept: Functional middleware is a plain function, not a class, that fits NestJS middleware signature.

Example: function logger(req, res, next) { console.log(`Request to ${req.url}`); next(); } This logs every request URL and then continues processing.

Result

Every request URL is printed in the console before the route handler runs.

Knowing that middleware can be simple functions makes it easy to write and test small reusable pieces.

3

Intermediate

Applying Middleware in NestJS Modules

Concept: Middleware functions are applied in modules using configure() method with MiddlewareConsumer.

In your module: import { MiddlewareConsumer, Module, NestModule, RequestMethod } from '@nestjs/common'; @Module({}) export class AppModule implements NestModule { configure(consumer: MiddlewareConsumer) { consumer .apply(logger) .forRoutes('*'); } } This applies logger middleware to all routes.

Result

All incoming requests pass through the logger middleware before reaching controllers.

Understanding how to connect middleware to routes lets you control where and when your middleware runs.

4

Intermediate

Controlling Middleware Execution Flow

🤔Before reading on: Do you think middleware can stop a request from reaching the controller? Commit to yes or no.

Concept: Middleware can decide to end the response early or pass control to the next handler by calling next().

Example: function auth(req, res, next) { if (!req.headers.authorization) { return res.status(401).send('Unauthorized'); } next(); } If no authorization header, response ends with 401. Otherwise, next() continues.

Result

Unauthorized requests get blocked early; authorized requests proceed normally.

Knowing middleware can short-circuit requests helps build security and validation layers efficiently.

5

Intermediate

Using Middleware with Route Filters

🤔Before reading on: Can you apply middleware only to specific routes or HTTP methods? Commit to yes or no.

Concept: Middleware can be applied selectively to routes or HTTP methods using forRoutes() with path and method filters.

Example: consumer .apply(logger) .forRoutes({ path: 'users', method: RequestMethod.GET }); This applies logger only to GET /users requests.

Result

Only requests matching the filter run the middleware; others skip it.

Selective middleware application improves performance and keeps unrelated routes clean.

6

Advanced

Combining Multiple Middleware Functions

🤔Before reading on: Do you think multiple middleware run in the order they are applied? Commit to yes or no.

Concept: You can chain multiple middleware functions; they run in the order applied, each calling next() to continue.

Example: consumer .apply(auth, logger) .forRoutes('profile'); First auth runs, then logger, then controller.

Result

Middleware run sequentially, allowing layered processing like auth then logging.

Understanding middleware order prevents bugs where middleware runs too early or late.

7

Expert

Middleware vs Interceptors and Guards

🤔Before reading on: Are middleware, guards, and interceptors interchangeable in NestJS? Commit to yes or no.

Concept: Middleware runs before route handlers and can modify requests; guards control access; interceptors transform responses or handle extra logic.

Middleware is low-level and works with raw requests. Guards check permissions and can block requests. Interceptors wrap around handlers to modify output or handle errors.

Result

Each has a distinct role; using them correctly leads to clean, maintainable code.

Knowing the differences helps choose the right tool for security, logging, or response shaping.

Under the Hood

NestJS middleware functions are standard Express middleware under the hood. When a request arrives, NestJS passes it through the middleware chain before reaching controllers. Each middleware receives the request and response objects and a next function. Calling next() passes control to the next middleware or handler. Middleware can modify request or response objects directly, affecting downstream processing.

Why designed this way?

NestJS builds on Express to leverage its mature middleware system, allowing developers to use familiar patterns. Functional middleware keeps things simple and flexible, avoiding the overhead of classes when not needed. This design balances ease of use with powerful control over request flow.

┌───────────────┐
│ Incoming Req  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Middleware 1  │
└──────┬────────┘
       │ next()
       ▼
┌───────────────┐
│ Middleware 2  │
└──────┬────────┘
       │ next()
       ▼
┌───────────────┐
│ Controller    │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Response Sent │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does middleware always run after guards? Commit to yes or no.

Common Belief: Middleware runs after guards and interceptors in NestJS.

Reality: Middleware runs before guards and interceptors because it is part of the underlying Express pipeline.

Why it matters: Misunderstanding this order can cause security checks to be bypassed or logging to miss early request data.

Quick: Can middleware modify the response after the controller sends it? Commit to yes or no.

Common Belief: Middleware can change the response even after the controller sends it.

Reality: Middleware runs before the controller sends the response, so it cannot modify the response after sending.

Why it matters: Expecting middleware to alter responses post-controller leads to bugs; interceptors are the correct tool for response transformation.

Quick: Is functional middleware always stateless? Commit to yes or no.

Common Belief: Functional middleware cannot hold or share state between requests.

Reality: Functional middleware can hold state using closures or external variables, but this must be done carefully to avoid bugs.

Why it matters: Assuming statelessness may cause unexpected behavior when middleware shares data across requests unintentionally.

Quick: Does applying middleware to '*' route mean it runs for all HTTP methods? Commit to yes or no.

Common Belief: Applying middleware to '*' runs it for all routes and all HTTP methods.

Reality: Applying to '*' runs middleware for all routes but only for HTTP methods supported by Express; some methods may be excluded.

Why it matters: Assuming full coverage can cause missing middleware on some HTTP methods, leading to security or logging gaps.

Expert Zone

1

Middleware functions can be asynchronous by returning promises or using async/await, but forgetting to await next() can cause subtle bugs.

2

Middleware order matters deeply; reversing order can break authentication or logging flows in production.

3

Functional middleware can be composed or wrapped to create reusable pipelines, enabling modular design patterns.

When NOT to use

Avoid using functional middleware for tasks that require access to NestJS dependency injection or lifecycle hooks; use class-based middleware or guards instead. For response transformation, prefer interceptors. For authorization logic, guards are more appropriate.

Production Patterns

In production, middleware is often layered: authentication middleware runs first, followed by logging and request parsing middleware. Middleware is selectively applied to routes to optimize performance. Error-handling middleware is added last to catch and format errors globally.

Connections

Express middleware

Functional middleware in NestJS is built on top of Express middleware.

Understanding Express middleware helps grasp NestJS middleware behavior and lifecycle.

HTTP request lifecycle

Middleware operates during the HTTP request lifecycle before the controller handles the request.

Knowing the HTTP lifecycle clarifies when and why middleware runs.

Assembly line manufacturing

Middleware processing is like an assembly line where each station adds or checks something before passing the product along.

This connection helps understand how middleware layers build up complex request handling step-by-step.

Common Pitfalls

#1 Middleware does not call next(), causing requests to hang.

Wrong approach:

function logger(req, res, next) {
console.log('Request received');
// forgot to call next()
}

Correct approach:

function logger(req, res, next) {
console.log('Request received');
next();
}

Root cause:

Forgetting to call next() stops the request chain, so the server never responds.

#2 Applying middleware globally but expecting it to run only on some routes.

Wrong approach:

consumer.apply(auth).forRoutes('*'); // expects auth only on /users

Correct approach:

consumer.apply(auth).forRoutes('users'); // applies only to /users route

Root cause:

Misunderstanding forRoutes() filters leads to middleware running too broadly or narrowly.

#3 Trying to use dependency injection inside functional middleware directly.

Wrong approach:

function myMiddleware(req, res, next) {
const service = this.myService; // undefined
next();
}

Correct approach:

Use class-based middleware with constructor injection or pass dependencies when creating functional middleware.

Root cause:

Functional middleware lacks NestJS context, so DI is unavailable without extra setup.

Key Takeaways

Functional middleware in NestJS is a simple function that runs before route handlers to process requests and responses.

Middleware can modify requests, block unauthorized access, or add logging, improving code reuse and organization.

Middleware runs before guards and interceptors, so understanding their order is crucial for security and behavior.

Applying middleware selectively to routes and methods optimizes performance and clarity.

Knowing when to use middleware versus guards or interceptors helps build clean, maintainable NestJS applications.