Global middleware in NestJS - Deep Dive

Overview - Global middleware

What is it?

Global middleware in NestJS is a function that runs before every route handler in the application. It can inspect, modify, or log requests and responses globally. This means it applies to all incoming HTTP requests without needing to attach it to each route individually. Middleware helps manage common tasks like authentication, logging, or request parsing.

Why it matters

Without global middleware, developers would have to add the same logic to every route, which is repetitive and error-prone. Global middleware centralizes common behaviors, making the app easier to maintain and consistent. It improves developer productivity and ensures that important checks or transformations happen uniformly across the app.

Where it fits

Before learning global middleware, you should understand basic NestJS concepts like modules, controllers, and providers. After mastering global middleware, you can explore more advanced topics like guards, interceptors, and exception filters, which also handle request lifecycle but at different stages.

Mental Model

Core Idea

Global middleware is a gatekeeper that processes every request before it reaches any route, applying shared logic across the whole app.

Think of it like...

Imagine a security guard at the entrance of a building who checks every visitor before they enter any room. This guard applies the same rules to everyone, ensuring safety and order.

┌─────────────────────────────┐
│       Incoming Request       │
└─────────────┬───────────────┘
              │
      ┌───────▼────────┐
      │ Global Middleware │
      └───────┬────────┘
              │
      ┌───────▼────────┐
      │  Route Handler  │
      └────────────────┘

Build-Up - 6 Steps

1

Foundation

What is Middleware in NestJS

Concept: Middleware is a function that runs during the request-response cycle before reaching route handlers.

In NestJS, middleware functions receive the request and response objects and can perform tasks like logging or modifying requests. They are similar to express middleware but integrated into NestJS's structure.

Result

You understand that middleware acts as a step in processing requests before routes handle them.

Knowing middleware is the first step to controlling how requests flow through your app and where you can insert shared logic.

2

Foundation

How to Create Middleware

Concept: Middleware is created as a class implementing the NestJS Middleware interface with a 'use' method.

You define a class with a 'use(req, res, next)' method. Inside, you can inspect or modify the request, then call 'next()' to continue the flow.

Result

You can write middleware that logs requests or checks headers before routes run.

Understanding the middleware structure helps you build reusable logic that fits NestJS's design.

3

Intermediate

Applying Middleware Globally

🤔Before reading on: Do you think global middleware is applied by listing it in every controller or by a single setup? Commit to your answer.

Concept: Global middleware applies to all routes by registering it once in the main application setup.

In NestJS, you use 'app.use()' in the main.ts file to apply middleware globally. This means every request passes through it automatically.

Result

Your middleware runs on every request without needing to attach it to individual routes or modules.

Knowing global middleware setup saves time and ensures consistent behavior across your entire app.

4

Intermediate

Order of Middleware Execution

🤔Before reading on: Does the order you register multiple global middleware affect their execution sequence? Commit to your answer.

Concept: Middleware runs in the order it is registered, so sequence matters for processing requests.

If you register middleware A then middleware B globally, A runs first, then B. This order affects how requests are modified or checked.

Result

You can control the flow of request processing by ordering middleware correctly.

Understanding execution order prevents bugs where middleware conflicts or unexpected behaviors occur.

5

Advanced

Middleware vs Guards and Interceptors

🤔Before reading on: Do you think middleware, guards, and interceptors run at the same time or different stages? Commit to your answer.

Concept: Middleware runs before route handlers; guards check permissions after middleware; interceptors wrap around route execution.

Middleware handles raw requests early. Guards decide if a request can proceed. Interceptors can modify responses or handle errors after route logic.

Result

You know where global middleware fits in the request lifecycle compared to other NestJS features.

Knowing these differences helps you choose the right tool for tasks like authentication, logging, or response transformation.

6

Expert

Performance and Side Effects of Global Middleware

🤔Before reading on: Can global middleware cause performance issues if it does heavy work on every request? Commit to your answer.

Concept: Global middleware runs on every request, so inefficient code here affects the whole app's speed and reliability.

Heavy computations, blocking calls, or unhandled errors in global middleware slow down all routes. Use async code carefully and avoid side effects that impact unrelated requests.

Result

You understand the importance of writing efficient, safe global middleware to keep your app responsive.

Recognizing the impact of global middleware on performance guides you to optimize or limit its scope when needed.

Under the Hood

NestJS builds on Express under the hood. When you register global middleware with 'app.use()', it attaches the middleware function to Express's middleware stack. Each incoming HTTP request passes through this stack in order. Middleware functions receive the raw request and response objects and a 'next' callback. Calling 'next()' passes control to the next middleware or route handler. NestJS wraps this process to integrate with its dependency injection and module system, but the core flow relies on Express's middleware mechanism.

Why designed this way?

NestJS uses Express middleware because Express is a widely adopted, battle-tested HTTP framework. This design allows NestJS to leverage existing middleware patterns and ecosystem tools. The global middleware concept centralizes common logic, reducing duplication and improving maintainability. Alternatives like applying middleware per route would be tedious and error-prone. The tradeoff is that global middleware must be efficient and carefully designed to avoid slowing down the entire app.

┌───────────────┐
│ Incoming HTTP │
│   Request     │
└───────┬───────┘
        │
┌───────▼─────────────┐
│ Express Middleware   │
│ Stack (global first) │
└───────┬─────────────┘
        │
┌───────▼─────────────┐
│ NestJS Middleware    │
│ (use method called)  │
└───────┬─────────────┘
        │
┌───────▼─────────────┐
│ Route Handler       │
│ (Controller method) │
└─────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does global middleware automatically handle errors thrown inside it? Commit to yes or no.

Common Belief: Global middleware automatically catches and handles errors so the app won't crash.

Reality: Middleware errors must be handled explicitly or passed to error-handling middleware; otherwise, they can crash the app.

Why it matters: Assuming automatic error handling leads to unexpected crashes and downtime in production.

Quick: Is global middleware the best place to put authentication logic? Commit to yes or no.

Common Belief: Global middleware is the ideal place for authentication checks since it runs on every request.

Reality: Authentication is better handled by guards, which are designed for authorization and can be applied selectively.

Why it matters: Using middleware for auth can complicate error handling and reduce flexibility in protecting routes.

Quick: Does the order of global middleware registration not affect their execution? Commit to yes or no.

Common Belief: The order you register global middleware does not matter; they all run independently.

Reality: Middleware runs in the order registered, so order affects how requests are processed and modified.

Why it matters: Ignoring order can cause bugs where middleware conflicts or unexpected data states occur.

Quick: Can you apply global middleware only to some routes by default? Commit to yes or no.

Common Belief: Global middleware can be configured to run only on specific routes by default.

Reality: Global middleware runs on all routes; to limit scope, you must use functional or module-scoped middleware.

Why it matters: Misunderstanding this leads to unintended middleware running on routes where it is not needed, causing overhead.

Expert Zone

1

Global middleware runs before NestJS pipes and guards, so it cannot access validated or transformed data from those layers.

2

Middleware functions do not have access to NestJS dependency injection by default; to use services, you must create middleware as injectable classes.

3

Global middleware can affect WebSocket or GraphQL requests only if explicitly integrated, as they bypass HTTP middleware by default.

When NOT to use

Avoid global middleware when logic should apply only to specific routes or modules; use scoped middleware or guards instead. For authorization, guards provide better control. For response transformation, interceptors are more appropriate.

Production Patterns

In production, global middleware is often used for logging, request ID generation, CORS setup, and body parsing. Authentication and authorization are handled by guards. Middleware is kept lightweight to avoid slowing down all requests. Complex logic is delegated to specialized layers.

Connections

HTTP Middleware (Express)

Global middleware in NestJS builds directly on Express middleware concepts.

Understanding Express middleware helps grasp how NestJS global middleware processes requests and integrates with the HTTP lifecycle.

Security Checkpoints

Global middleware acts like a security checkpoint filtering all incoming traffic.

Knowing how physical security checkpoints work clarifies why middleware must be efficient and consistent to avoid bottlenecks.

Assembly Line Processing

Middleware functions are like stations on an assembly line, each performing a task before passing the product along.

This connection helps understand the importance of order and efficiency in middleware execution.

Common Pitfalls

#1 Writing heavy synchronous code in global middleware causing slow responses.

Wrong approach:

use(req, res, next) {
// heavy computation blocking event loop
for(let i=0; i<1e9; i++) {}
next();
}

Correct approach:

async use(req, res, next) {
await someAsyncTask();
next();
}

Root cause:

Misunderstanding that middleware runs on every request and blocking code delays all responses.

#2 Not calling next() in middleware, causing requests to hang.

Wrong approach:

use(req, res, next) {
console.log('Request received');
// missing next()
}

Correct approach:

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

Root cause:

Forgetting that next() passes control forward, so omitting it stops the request pipeline.

#3 Trying to inject services directly into middleware without making it injectable.

Wrong approach:

export class LoggerMiddleware {
constructor(private readonly logger: LoggerService) {}
use(req, res, next) {
this.logger.log('Request');
next();
}
}

Correct approach:

@Injectable()
export class LoggerMiddleware {
constructor(private readonly logger: LoggerService) {}
use(req, res, next) {
this.logger.log('Request');
next();
}
}

Root cause:

Not marking middleware as injectable prevents NestJS from injecting dependencies.

Key Takeaways

Global middleware in NestJS runs on every incoming HTTP request before any route handler.

It centralizes common logic like logging or request parsing, improving maintainability and consistency.

Middleware runs in the order registered, so sequence affects request processing flow.

Global middleware should be efficient and error-safe to avoid slowing or crashing the entire app.

For tasks like authentication or response transformation, guards and interceptors are often better suited.