Middleware Fundamentals

An Express application is, in the official wording, a series of middleware function calls. A middleware function is an ordinary JavaScript function that receives the request object (req), the response object (res) and a function conventionally named next. Each function can do any combination of four things:

Express keeps an ordered list of these functions, called the stack, and runs the request through the list from the first entry to the last. The first function that sends a response ends the cycle; the functions after it never run for that request. If a function neither responds nor calls next(), the request hangs until the client gives up, because nothing else will ever touch it.

Since Express 5 the stack is managed by the standalone router package (the 2.x line, maintained by the pillarjs organization), which Express depends on directly; in Express 4 the same code lived inside Express itself. Application objects, express.Router() instances and route objects all use the same layer machinery, which is why the rules on this page apply equally to all of them.

The shape of a normal middleware function is fixed:

Source: Express: Writing middleware for use in Express apps

The arguments are the Node.js http.IncomingMessage and http.ServerResponse objects extended by Express with its own properties and methods, plus next. Express never inspects what the function returns, with one exception described in Async middleware in Express 5: if it returns a promise, Express waits on that promise only to catch a rejection.

What a function does at the end of its work decides what happens to the request:

The two strings 'route' and 'router' are special values, not errors. Any other argument other than a falsy one is an error, including a string such as 'forbidden'. Do not pass strings to next() expecting a message; pass an Error. The figure shows the four exits from a layer.

The word "onion" is a convenient picture of the nesting (application, then router, then route), not a promise that control returns outward the way it does in Koa. In Express, next() returns undefined and a middleware does not get a second turn when the downstream handlers finish. If you need to act after the response has been sent, listen for the response’s finish event, as the first example below does.

The following program wires a logger, a JSON body parser, a path-scoped middleware, a router with a two-step route, a 404 handler and an error handler. Run it with npm install express and node pipeline.mjs.

Source: Express: Writing middleware, Express: Using middleware

Requesting /books/1 runs layers 1, 2, 3 and then the router; the first handler stores the book in res.locals, the second sends it. Requesting /books/99 makes the first handler call next('route'), which skips the second handler and lands in the fallback route. Requesting /shelves passes through layers 1 and 2, matches nothing else and reaches the 404 layer. Notice that the router is mounted on the same /books prefix as the path-scoped logger: mounting is just a layer registered with a path, so the order in which app.use() calls appear is the order in which requests are processed.

Express has no priority numbers, phases or dependency declarations. The only rule is registration order: for each request, the router walks the stack from the first registered layer to the last and runs every layer whose path and method match, until one ends the cycle. Everything else follows from that rule.

A sound order for most applications is:

Some consequences worth memorising:

The official guide groups middleware by where it is attached and who wrote it. The categories overlap, since a function is just a function; the category tells you how the stack treats it.

Two practical differences between application-level and router-level middleware matter in large applications. First, router-level middleware sees req.url relative to the mount path while req.baseUrl holds the mount path and req.originalUrl keeps the full URL, so a router can be mounted at several prefixes without changes. Second, a router is itself a middleware function: app.use('/books', router) just registers it as a layer, which is why routers nest inside routers.

app.use() and router.use() accept an optional first argument that restricts the layer to requests whose path starts with that mount path. The comparison is by whole path segments, not raw characters, and the mount path is removed from req.url for the duration of the layer. With the path-to-regexp 8 syntax that Express 5 uses (through router 2), a mount path may be a string, a path with named parameters such as /books/:id, a regular expression, or an array of any of these. The wildcard * on its own is no longer a valid path in Express 5: use a path-less app.use(fn) to run for everything, or a named wildcard such as /{*splat} where the wildcard value is needed. The full syntax is in Route Paths & Parameters.

Every registration method accepts more than one function. All of these are equivalent ways of building a sub-stack:

Source: Express: Using middleware

Arrays make it easy to share a reusable guard stack between routes (for example [authenticate, requireRole('editor')]) without repeating it. Express flattens the arrays when the route is registered, so they have no run-time cost.

Most useful middleware needs configuration: which header carries the API key, which roles may pass, how long a response may be cached. The convention, used by every Express middleware package, is a factory: an outer function that takes options and returns the (req, res, next) function. express.json({ limit: '1mb' }), cors({ origin }) and morgan('tiny') are all factories.

Source: Express: Writing middleware (configurable middleware)

Design rules that make factories pleasant to use:

In Express 4, an async middleware function that threw or awaited a rejected promise produced an unhandled rejection: Express never saw the failure, the request hung, and Node.js either logged a warning or, from Node.js 15 on, terminated the process. The usual workarounds were a try/catch that called next(err) in every handler, a small wrapper around each handler, or the express-async-errors package that patched the framework.

Express 5 fixes this at the source. When a layer’s function returns a promise (that is, when it is an async function or returns any thenable), the router attaches a rejection handler, and a rejection is forwarded to next(err) automatically. A thrown exception inside an async function is a rejection, so it reaches the error handlers too. If the rejection reason is falsy, the router wraps it in an Error so that the error path still runs. This applies to route handlers, to app.use() and router.use() layers, and to router.param() callbacks alike; it does not apply to error-handling middleware itself being invoked, whose own failures are reported through the same mechanism.

Source: Express: Error handling

The new behaviour has limits that the official guide spells out and that cause real bugs:

Error handling in depth, including the default handler and Problem Details responses, is the subject of Error Handling.

Error-handling middleware is defined like any other middleware but with four parameters, (err, req, res, next). Express decides whether a function is an error handler by its declared length, so the fourth parameter must be present even if the function never uses it. Two consequences follow:

When no error handler takes the error, the built-in finalhandler answers: it uses err.status or err.statusCode when they are between 400 and 599 (otherwise 500), copies err.headers and, outside production, includes the stack trace in the HTML body. If headers were already sent, it closes the connection instead. Always define your own handler that returns the format your clients expect, and set NODE_ENV=production in production so that stack traces stay out of responses.

Middleware often produces a value that later layers or the view need: the authenticated user, the loaded book, the request ID, the current language. There are three places to put it:

res.locals is an object created per response, so values cannot leak between concurrent requests, unlike a variable declared at module level. Prefer it to inventing properties on req when the data has no established name; plain properties on req work but collide easily with the framework’s own (req.query, req.body, req.params, req.path) and with other middleware. In TypeScript, res.locals has the type Record<string, any> & Locals, which can be narrowed through the Locals interface or a generic parameter (see TypeScript with Express).

The official view-locals example in the expressjs/express repository shows three ways of getting data into a view: middleware that loads data and stores it for the route, a route that builds its locals itself, and values passed straight to res.render(). The Bookshelf version below follows the same ideas and uses the EJS template engine (npm install express ejs). Create the two files shown and run node view-locals.mjs.

Source: expressjs/express: examples/view-locals

Source: Express: Using template engines

When res.render() builds the variable set it merges, from lowest to highest priority, app.locals, res.locals and the object passed to render(); on a name clash the object passed to render() wins. Express 5 always renders asynchronously (Express 4 could render synchronously with some engines, which caused subtle ordering bugs), and an error during rendering is passed to next(err) when no callback is supplied. The <%= %> tag HTML-escapes its value; use the unescaped tag only for markup you built yourself. Views and engines are covered in Template Engines & Views.

The migration guide lists every removed method and the codemods that rewrite them; this page covers only what affects how middleware is written. The Express team has not announced a version 6, so nothing here depends on one.

A habit that prevents most of these: when adding a layer, write down which later layers depend on it and which earlier layers it depends on, then place it accordingly. A short test that exercises the application with supertest and checks req-dependent behaviour in the order the layers run catches ordering errors long before production; see Testing.

The four books consulted for this section target Express 4.0 to 4.18 and Node.js 0.10 to 20. Their middleware chapters remain a good picture of the concepts, but several practices have since changed: