🔗 Custom Middleware Development

The Middleware Pipeline

Middleware is any function that sits between the incoming request and the outgoing response. Express hands each request to your middleware functions in the order you registered them. Each function can inspect the request, modify it, end the response early, or call next() to pass control to the next function in line.

🏭 The assembly-line analogy. Think of middleware as an assembly line. Raw materials (the request) enter the factory. Each workstation (a middleware function) does one job — it can modify the item and pass it on, reject a defective item (send an error), or finish the product early and ship it (send a response). The final assembly is your route handler. Different products (routes) can run down different lines with different stations.

This ordered, composable design is why Express feels so flexible: complex behavior emerges from stacking simple, single-purpose functions.

Anatomy of a Middleware Function

A middleware function has a fixed signature — three parameters — and follows a predictable rhythm:

function myMiddleware(req, res, next) {
  // 1. Inspect the request
  console.log(`${req.method} ${req.url}`);

  // 2. Optionally attach data for later middleware/handlers
  req.requestTime = Date.now();

  // 3. Either end the cycle:  res.send(...)  /  res.json(...)
  //    OR hand off to the next middleware:
  next();
}

app.use(myMiddleware); // register it globally

The golden rule: every middleware must either send a response or call next(). Do neither and the request hangs forever. Do both and you'll get an "headers already sent" error.

Error-handling middleware

Express recognizes error middleware purely by its arity — four parameters instead of three. It only runs when something calls next(err), and it must be registered last:

// Four parameters (err first) = error handler. Register it AFTER all routes.
function errorHandler(err, req, res, next) {
  console.error(err.stack);
  res.status(err.statusCode || 500).json({
    error: {
      message: process.env.NODE_ENV === 'production'
        ? 'An unexpected error occurred'
        : err.message,
    },
  });
}

app.use(errorHandler);

Purpose-Specific Middleware

Let's write the middleware every real API eventually needs. Each is small, focused, and reusable.

Request logging

A logger records what came in and how long it took. Listening on the response's finish event lets you measure duration accurately:

const requestLogger = (req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    const ms = Date.now() - start;
    console.log(`${new Date().toISOString()} ${req.method} ${req.originalUrl} → ${res.statusCode} (${ms}ms)`);
  });
  next();
};

app.use(requestLogger);

Authentication (JWT)

Auth middleware verifies a token and attaches the decoded user to req so downstream handlers know who's calling:

const jwt = require('jsonwebtoken');

const authenticate = (req, res, next) => {
  const header = req.headers.authorization;
  if (!header) {
    return res.status(401).json({ message: 'Authorization header is missing' });
  }
  const [scheme, token] = header.split(' ');
  if (scheme !== 'Bearer' || !token) {
    return res.status(401).json({ message: 'Use: Authorization: Bearer <token>' });
  }
  try {
    req.user = jwt.verify(token, process.env.JWT_SECRET);
    next();
  } catch (err) {
    const message = err.name === 'TokenExpiredError' ? 'Token has expired' : 'Invalid token';
    return res.status(401).json({ message });
  }
};

Request validation

Validation middleware rejects bad input before it reaches your business logic, returning a helpful 400:

const validateUserCreation = (req, res, next) => {
  const { name, email, password } = req.body;
  const errors = [];

  if (!name || name.length < 2) {
    errors.push({ field: 'name', message: 'Name must be at least 2 characters' });
  }
  if (!/^\S+@\S+\.\S+$/.test(email || '')) {
    errors.push({ field: 'email', message: 'Email format is invalid' });
  }
  if (!password || password.length < 8 || !/[A-Z]/.test(password) || !/[0-9]/.test(password)) {
    errors.push({ field: 'password', message: 'Password needs 8+ chars, an uppercase letter and a number' });
  }

  if (errors.length) {
    return res.status(400).json({ success: false, error: { message: 'Validation failed', details: errors } });
  }
  next();
};

app.post('/api/users', validateUserCreation, (req, res) => {
  res.status(201).json({ success: true, message: 'User created' });
});

Global, Path & Route Scoping

Middleware can apply to everything, to a path prefix, or to a single route. Choosing the right scope keeps your app efficient and secure:

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

// GLOBAL — runs for every request
app.use(express.json());
app.use(requestLogger);

// PATH-SPECIFIC — only requests starting with /api
app.use('/api', apiKeyValidator);

// ROUTE-SPECIFIC — only this endpoint, and in this order
app.get('/users/:id', authenticate, (req, res) => {
  res.json(req.user);
});

// MULTIPLE per route — they run left to right
app.post('/users', authenticate, validateUserCreation, (req, res) => {
  res.status(201).json({ created: true });
});

// ROUTER-LEVEL — applies to every route in the router
const router = express.Router();
router.use(someSharedMiddleware);
router.get('/a', handlerA);
router.get('/b', handlerB);
app.use('/feature', router);

A clean project mirrors this tree in its file layout: a thin app.js wires global middleware and mounts routers, while each router file owns its own resource-specific middleware.

// routes/users.js
const express = require('express');
const router = express.Router();
const { authenticate, authorize } = require('../middleware/auth');
const { validateUser } = require('../middleware/validation');

router.get('/', authenticate, authorize(['admin']), userController.getAll);
router.get('/me', authenticate, userController.getCurrent);
router.post('/', validateUser, userController.create);
router.put('/:id', authenticate, validateUser, userController.update);

module.exports = router;

The Factory Pattern

Sometimes middleware needs configuration — "allow only these roles", "cache for this many seconds". You can't pass arguments to a middleware directly (Express calls it with req, res, next), so you write a factory: a function that returns a middleware, capturing the config in a closure.

// A factory that builds role-based authorization middleware
const authorize = (allowedRoles = []) => {
  const roles = Array.isArray(allowedRoles) ? allowedRoles : [allowedRoles];
  return (req, res, next) => {
    if (!req.user) {
      return res.status(401).json({ message: 'Not authenticated' });
    }
    if (roles.length && !roles.includes(req.user.role)) {
      return res.status(403).json({ message: 'Insufficient permissions' });
    }
    next();
  };
};

// Each call produces a fresh, configured middleware
app.get('/api/admin', authenticate, authorize('admin'), adminController.dashboard);
app.get('/api/reports', authenticate, authorize(['admin', 'manager']), reportController.list);

The same pattern powers configurable rate limiters, feature flags, and caches. Here's a compact in-memory rate limiter built as a factory (use express-rate-limit in production, but this shows the mechanics):

const rateLimit = ({ windowMs = 60_000, max = 100, message = 'Too many requests' } = {}) => {
  const hits = new Map(); // key → { count, resetAt }

  return (req, res, next) => {
    const key = req.ip;
    const now = Date.now();
    let entry = hits.get(key);

    if (!entry || now > entry.resetAt) {
      entry = { count: 0, resetAt: now + windowMs };
    }
    entry.count += 1;
    hits.set(key, entry);

    res.setHeader('X-RateLimit-Limit', max);
    res.setHeader('X-RateLimit-Remaining', Math.max(0, max - entry.count));

    if (entry.count > max) {
      return res.status(429).json({ success: false, error: { message } });
    }
    next();
  };
};

// Loose global limit, strict login limit
app.use(rateLimit({ windowMs: 15 * 60_000, max: 100 }));
app.post('/api/auth/login', rateLimit({ windowMs: 60 * 60_000, max: 5, message: 'Too many login attempts' }), loginHandler);

Asynchronous Middleware

Middleware often does async work — a database lookup, an external API call. The danger: if a rejected promise isn't caught, older Express versions silently hang the request. There are two robust approaches.

1. try/catch with async/await

const loadUser = async (req, res, next) => {
  try {
    const user = await User.findById(req.params.id);
    if (!user) {
      const err = new Error('User not found');
      err.statusCode = 404;
      throw err;
    }
    req.user = user;
    next();
  } catch (err) {
    next(err); // hand the error to the error-handling middleware
  }
};

2. An asyncHandler wrapper (removes the boilerplate)

// One helper wraps any async handler and forwards rejections to next()
const asyncHandler = (fn) => (req, res, next) =>
  Promise.resolve(fn(req, res, next)).catch(next);

app.get('/api/users/:id', asyncHandler(async (req, res) => {
  const user = await User.findById(req.params.id);
  if (!user) {
    const err = new Error('User not found');
    err.statusCode = 404;
    throw err; // caught by asyncHandler, sent to error middleware
  }
  res.json(user);
}));

Testing Middleware

Because middleware is just a function of (req, res, next), it's easy to unit-test with fakes. Here's an auth middleware tested with Jest — no server required:

const jwt = require('jsonwebtoken');
const authenticate = require('../middleware/authenticate');

jest.mock('jsonwebtoken');

describe('authenticate middleware', () => {
  let req, res, next;

  beforeEach(() => {
    req = { headers: {} };
    res = { status: jest.fn().mockReturnThis(), json: jest.fn() };
    next = jest.fn();
  });

  test('returns 401 when no Authorization header', () => {
    authenticate(req, res, next);
    expect(res.status).toHaveBeenCalledWith(401);
    expect(next).not.toHaveBeenCalled();
  });

  test('calls next and sets req.user on a valid token', () => {
    const user = { id: '123', role: 'user' };
    req.headers.authorization = 'Bearer valid.token';
    jwt.verify.mockReturnValue(user);

    authenticate(req, res, next);

    expect(req.user).toEqual(user);
    expect(next).toHaveBeenCalled();
    expect(res.status).not.toHaveBeenCalled();
  });
});

For end-to-end confidence, integration tests with supertest exercise the middleware inside a real Express app:

const request = require('supertest');
const express = require('express');
const authenticate = require('../middleware/authenticate');

const app = express();
app.get('/protected', authenticate, (req, res) => res.json({ user: req.user }));

test('rejects requests without a token', async () => {
  const res = await request(app).get('/protected');
  expect(res.status).toBe(401);
});

Hands-on Exercise

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

// 1. Timing logger
const requestTimer = (req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    console.log(`${req.method} ${req.originalUrl} → ${res.statusCode} (${Date.now() - start}ms)`);
  });
  next();
};

// 3. Fake auth for testing
const attachUser = (req, res, next) => {
  req.user = { id: 1, role: 'editor' };
  next();
};

// 2. Authorization factory
const authorize = (roles = []) => (req, res, next) => {
  if (!req.user) return res.status(401).json({ message: 'Not authenticated' });
  if (!roles.includes(req.user.role)) {
    return res.status(403).json({ message: 'Insufficient permissions' });
  }
  next();
};

app.use(requestTimer);
app.use(attachUser);

app.get('/admin', authorize(['admin']), (req, res) => res.json({ ok: 'admin area' }));
app.get('/posts', authorize(['admin', 'editor']), (req, res) => res.json({ ok: 'posts' }));

app.listen(3000, () => console.log('http://localhost:3000'));
// GET /admin  → 403 (editor blocked)
// GET /posts  → 200 (editor allowed)

Best Practices

Summary & Quiz

📚 Further Reading

• Express — Using Middleware
• Express — Writing Middleware
• morgan — HTTP request logger
• Passport — authentication middleware
• express-validator

🚀 What's Next?

You've seen middleware forward errors with next(err) — but where do those errors go, and how should they be shaped, logged, and returned? Next, Error Handling Strategies builds a complete, production-grade error pipeline.