🔗 Middleware Architecture and Flow

What Is Middleware?

Middleware is simply a function that sits in the middle of the journey between an incoming HTTP request and the response Express sends back. Each middleware function gets a chance to inspect the request, modify it, respond to it, or hand it along to the next function in line. That's the whole idea — Express is, at its core, little more than a pipeline of middleware functions run in order.

💡 Assembly-line analogy: Picture a request as a product moving down a factory conveyor belt. Each middleware is a specialised station: one inspects the label (logging), one attaches a part (parses the body), one checks the product is authorised to continue (authentication). The product moves from station to station until it is finished (a response is sent) or pulled off the line for repair (an error handler).

Because every middleware sees the same req and res objects, they can cooperate: an early one can attach req.user and a later one can read it. In Express, a middleware function can do any of four things:

• Execute arbitrary code (log, time, measure)
• Modify the req and res objects (attach data, set headers)
• End the request–response cycle by sending a response
• Call next() to pass control to the next middleware in the stack

The Middleware Signature

Every Express middleware function shares the same shape. It receives three parameters that give it full access to the request–response cycle:

// The canonical middleware signature
function logger(req, res, next) {
  // 1. Do work — here we log the method and URL
  console.log(`${req.method} ${req.originalUrl}`);

  // 2. Hand control to the next middleware in the chain
  next();
}

• req — the request object: method, URL, headers, params, query, and (after parsing) body.
• res — the response object: used to set status, headers, and send data back.
• next — a function you call to pass control onward. Forget to call it (and don't send a response) and the request hangs forever.

There is a second, special signature reserved for error-handling middleware. It takes four arguments, and Express recognises it purely by that arity:

// Error-handling middleware — note the leading `err`
function errorHandler(err, req, res, next) {
  console.error(err.stack);
  res.status(500).json({ error: 'Something broke!' });
}

The Request–Response Flow

Let's trace an actual request through a small stack. A logger runs first, then a body parser, then an authentication check, and finally the route handler. If authentication fails, control jumps straight to the error handler instead.

The same story told as a sequence of hand-offs between the participants:

Reading that flow in plain English:

1. The client sends an HTTP request; Express hands it to the first middleware (the logger).
2. The logger records the request details and calls next().
3. The body parser turns the raw body into req.body and calls next().
4. The auth middleware checks credentials. On success it calls next() to reach the route handler; on failure it calls next(error) to jump to the error handler.
5. Whichever handler runs last sends a response, ending the cycle.

The Three Faces of next()

The next() function is the steering wheel of the middleware chain. Calling it with different arguments sends the request in different directions:

Here is all three in a single route so you can see them side by side:

app.get('/example',
  (req, res, next) => {
    console.log('First middleware');
    if (req.query.skipRoute) return next('route');      // jump to the next /example route
    if (req.query.error)     return next(new Error('Boom')); // jump to the error handler
    next();                                              // continue to the next middleware
  },
  (req, res, next) => {
    console.log('Second middleware — skipped when skipRoute or error is set');
    next();
  },
  (req, res) => {
    res.send('Regular response');
  }
);

// A second handler for the same path — reached only via next('route')
app.get('/example', (req, res) => {
  res.send('Alternative response');
});

// Error handler — reached only via next(err)
app.use((err, req, res, next) => {
  res.status(500).send(`Error response: ${err.message}`);
});

💡 Conveyor-belt analogy: A plain next() moves the product to the next station. next('route') is a diversion onto a different belt. next(err) is the emergency stop that routes the product to quality control.

Execution Order & Mount Paths

Middleware runs in the order it is registered. This is the single most important rule to internalise, because a body parser registered after a route can't help that route, and an auth check registered after a protected handler protects nothing.

A middleware's mount path decides which requests it applies to. With no path it runs for every request; with a path prefix it runs only for URLs beginning with that prefix:

const express = require('express');
const app = express();

// (1) No path — runs for EVERY request, first
app.use((req, res, next) => {
  req.startedAt = Date.now();
  next();
});

// (2) Path-scoped — runs only for URLs beginning with /api
app.use('/api', (req, res, next) => {
  req.isApiRequest = true;
  next();
});

// (3) No path again — runs after (1) for every request
app.use((req, res, next) => {
  console.log(`So far: ${Date.now() - req.startedAt}ms`);
  next();
});

app.get('/api/data', (req, res) => {
  res.json({ isApiRequest: req.isApiRequest, ms: Date.now() - req.startedAt });
});

app.get('/home', (req, res) => {
  res.json({ isApiRequest: req.isApiRequest || false });
});

app.listen(3000, () => console.log('http://localhost:3000'));

The stack a request runs through depends on its URL:

• GET /api/data → (1) → (2) → (3) → handler (matches the /api mount)
• GET /home → (1) → (3) → handler (skips the /api-scoped middleware)

Mount paths can be more than a simple string — Express accepts a path prefix, a regular expression, or an array:

app.use('/api', apiMiddleware);            // string prefix
app.use(/user/, userMiddleware);           // regular expression
app.use(['/api', '/admin'], secureMiddleware); // array of paths

Error-Handling Middleware

Errors need their own lane. When any middleware calls next(err) — or throws inside an async handler that you forward — Express skips every remaining regular middleware and looks for the first error-handling middleware (the four-argument kind). Register it last, after all routes.

// A route that forwards its error instead of crashing the process
app.get('/data', (req, res, next) => {
  if (!req.query.id) {
    return next(new Error('id query parameter is required'));
  }
  res.json({ ok: true });
});

// Central error handler — LAST, and note the four parameters
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(err.statusCode || 500).json({ error: err.message });
});

With modern async/await handlers, wrap the body in try/catch and forward with next(err) so the central handler stays in charge:

app.get('/users/:id', async (req, res, next) => {
  try {
    const user = await db.findUser(req.params.id);
    if (!user) {
      const err = new Error('User not found');
      err.statusCode = 404;
      throw err;
    }
    res.json(user);
  } catch (err) {
    next(err); // hand off to the central error handler
  }
});

Hands-on Exercise

const express = require('express');
const app = express();

// (1) Global logger
app.use((req, res, next) => {
  req.receivedAt = Date.now();
  console.log(`${req.method} ${req.originalUrl}`);
  next();
});

// (2) API tagger — only for /api/*
app.use('/api', (req, res, next) => {
  req.isApi = true;
  next();
});

// (3) Protected route
app.get('/api/secret', (req, res, next) => {
  if (req.get('x-key') !== 'let-me-in') {
    return res.status(403).json({ error: 'Forbidden' });
  }
  res.json({
    message: 'Welcome in',
    isApi: req.isApi,
    elapsedMs: Date.now() - req.receivedAt
  });
});

// (4) Central error handler — LAST
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(err.statusCode || 500).json({ error: err.message });
});

app.listen(3000, () => console.log('http://localhost:3000'));

Best Practices

Summary & Quiz

📚 Further Reading

• Express — Using middleware
• Express — Writing middleware
• Express — Error handling

🚀 What's Next?

Now that you understand how the chain works, the next lesson surveys the middleware you'll reach for constantly — Express's built-in parsers and static server, plus the essential third-party packages for logging, security, and CORS.