Express.js 5 Migration Guide

Introduction

Express.js has been the backbone of Node.js web development for over a decade. After years of anticipation, Express 5.0 arrived in October 2024, bringing modernizations that align the framework with current Node.js capabilities while addressing long-standing issues. This comprehensive guide walks you through every aspect of migrating your Express 4 applications to Express 5, from understanding breaking changes to implementing best practices that leverage the framework's improvements.

Express 5 represents a careful balance between progress and stability. The development team focused on three primary goals: modernizing the codebase to support Node.js 18 and above, improving security by upgrading the underlying path-to-regexp library, and enhancing developer experience through better async error handling. Unlike major version bumps in some frameworks that introduce sweeping architectural changes, Express 5 maintains the familiar API structure that millions of developers know while systematically removing deprecated features and fixing behavioral inconsistencies.

The decision to upgrade depends on your application's complexity and dependencies. New projects should begin with Express 5 from the start, taking advantage of its improvements. Existing applications require careful evaluation of dependencies, particularly if they rely on any of the removed or changed APIs discussed in this guide.

Why Migrate to Express 5

The transition to Express 5 offers tangible benefits that justify the migration effort. Performance improvements come from the upgraded path-to-regexp library, which handles route matching more efficiently and reduces the risk of regular expression denial of service (ReDoS) attacks. The automatic handling of promise rejections in middleware and route handlers eliminates boilerplate error-handling code that developers have been writing for years, resulting in cleaner, more maintainable codebases.

Security enhancements address vulnerabilities that accumulated over Express 4's extended lifespan. The path-to-regexp upgrade from version 0.x to 8.x eliminates several classes of potential ReDoS vulnerabilities by removing support for ambiguous inline regex patterns in route definitions. Additionally, stricter validation of status codes and other response properties prevents common mistakes that could lead to unexpected behavior.

Future-proofing your application is perhaps the most compelling reason to migrate. Express 5 requires Node.js 18 or higher, ensuring compatibility with modern JavaScript features and the latest Node.js runtime improvements. The Express team has committed to ongoing maintenance, meaning security patches and feature updates will continue for the foreseeable future. For more context on error handling patterns that work well with Express 5, see our related guide.

Prerequisites and Preparation

Before beginning your migration, verify that your development environment meets Express 5's requirements and that your application dependencies are compatible.

System Requirements

Express 5 requires Node.js version 18 or higher. This minimum version requirement ensures access to modern JavaScript features including improved async handling, native fetch support, and optimized runtime performance. Check your current Node.js version by running:

node --version

If you're using an older version, you'll need to upgrade Node.js before proceeding with the Express upgrade.

For production environments, confirm that your deployment infrastructure supports Node.js 18 or later. Containerized deployments using Docker should update their base images to tags like node:18-alpine or later. Cloud platform functions (AWS Lambda, Google Cloud Functions, Azure Functions) may require runtime configuration updates if they're not already set to Node.js 18 or 20.

Package manager compatibility is generally straightforward since npm and yarn both support Node.js 18 and above. However, if you're using an older version of npm (prior to 8.x), consider upgrading to benefit from faster dependency resolution and improved deduplication.

Dependency Audit

Create a complete inventory of your project's dependencies and their Express-related versions. Your package.json file likely lists express as a direct dependency, but your application may also depend on middleware packages, template engines, and other libraries that interact with Express internals.

Run the following command to identify all packages:

npm list --depth=0

For each dependency, check its documentation or changelog for Express 5 compatibility information. Most popular middleware packages have released Express 5-compatible versions. Pay particular attention to:

• Authentication middleware (Passport.js, express-jwt)
• Session management (express-session, connect-redis)
• Body parsing (body-parser is now built into Express)
• Template engines (EJS, Pug, Handlebars)

If you maintain internal packages that wrap Express functionality, test those packages against Express 5 before upgrading your main application. Custom middleware and utilities may need updates to accommodate changed APIs. For understanding middleware patterns in modern JavaScript applications, see our guide on trunk-based development which covers deployment and testing strategies.

Breaking Changes: Removed Methods

Express 5 removes several deprecated methods that existed in Express 4. Understanding these removals helps you identify specific changes needed in your codebase. According to the Express.js official migration guide, each removal includes the rationale behind the change and a recommended migration path.

app.del() -- HTTP DELETE Method Registration

The app.del() method was a historical artifact from early JavaScript when delete was a reserved keyword. Modern JavaScript (ES6+) allows reserved keywords as property names, making app.delete() the preferred approach.

// Express 4 (deprecated)
app.del('/users/:id', (req, res) => {
 User.delete(req.params.id)
 .then(() => res.sendStatus(204))
 .catch(next);
});

// Express 5
app.delete('/users/:id', async (req, res) => {
 await User.delete(req.params.id);
 res.sendStatus(204);
});

Notice how the Express 5 version leverages automatic promise rejection handling--the rejected promise automatically routes to error-handling middleware without requiring explicit try/catch blocks. This simplification aligns with modern error handling best practices in JavaScript applications.

req.param(name) -- Parameter Retrieval

The req.param(name) method has been removed due to its confusing behavior and potential security implications. This method searched across req.params, req.body, and req.query without clarity about which source would provide the value.

// Express 4 (removed)
const id = req.param('id'); // Could come from params, body, or query

// Express 5 - explicit access
const idFromParams = req.params.id;
const idFromBody = req.body.id;
const idFromQuery = req.query.id;

This change improves code clarity and prevents subtle bugs where the wrong data source was consulted. Always access request data from the appropriate source explicitly. Following consistent CSS naming conventions in your codebase makes refactoring and maintaining these changes significantly easier.

Changed Behaviors

Beyond removed methods, Express 5 modifies the behavior of several existing APIs.

Path Route Matching Syntax

The path-to-regexp library upgrade from 0.x to 8.x brings significant changes to route matching.

Wildcard Parameters

The * wildcard must now have a name:

// Express 4
app.get('/*', (req, res) => res.send('catch-all'));

// Express 5
app.get('/*splat', (req, res) => res.send('catch-all'));

Optional Parameters

The optional marker ? is no longer supported directly:

// Express 4
app.get('/:file.:ext?', (req, res) => res.send('file'));

// Express 5
app.get('/:file{.:ext}', (req, res) => res.send('file'));

Regex Patterns

Inline regex patterns are no longer supported:

// Express 4 (removed)
app.get('/:id(\\d+)', (req, res) => res.send('numeric id'));

// Express 5
app.get('/:id', (req, res) => {
 if (!/^\d+$/.test(req.params.id)) {
 return res.status(400).send('ID must be numeric');
 }
 res.send('numeric id');
});

Automatic Promise Rejection Handling

Express 5 introduces automatic forwarding of rejected promises to error-handling middleware:

// Express 4 - required try/catch
app.get('/users/:id', async (req, res, next) => {
 try {
 const user = await User.findById(req.params.id);
 res.json(user);
 } catch (err) {
 next(err);
 }
});

// Express 5 - errors automatically forwarded
app.get('/users/:id', async (req, res) => {
 const user = await User.findById(req.params.id);
 res.json(user);
});

This change significantly simplifies async error handling. If the async function rejects, Express automatically invokes the error-handling middleware with the rejected value. Understanding these error handling patterns is essential for building robust Node.js applications.

New Features and Improvements

Asynchronous res.render()

The res.render() method now enforces asynchronous behavior for all view engines. This prevents bugs caused by synchronous template engines that violated the recommended interface.

Brotli Compression Support

Express 5 adds native support for Brotli compression:

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

const app = express();
app.use(compression());

The middleware automatically uses Brotli when the client supports it (indicated by the br Accept-Encoding value), achieving better compression than gzip for text-based responses.

Reintroduced app.router

The app.router object, removed in Express 4, has returned as a reference to the base Express router. For teams considering headless CMS options with Express backends, this stable router API provides a reliable foundation for building API-driven applications.

Migration Workflow

Following a structured workflow minimizes risk and ensures complete coverage. For teams practicing trunk-based development, consider creating a feature branch specifically for this migration.

Step 1: Install and Test

npm install express@5

Run your existing test suite to identify failures.

Step 2: Identify Breaking Changes

Use the automated codemod from the @expressjs/codemod repository to apply common changes:

npx @expressjs/codemod upgrade

Step 3: Test Incrementally

Address remaining failures systematically. Use integration tests to verify end-to-end behavior.

Step 4: Verify Production Behavior

Deploy to a staging environment that mirrors production.

Common Migration Pitfalls

Route Parameter Handling

Wildcard parameters catching arrays instead of strings:

app.get('/*splat', (req, res) => {
 const pathParts = req.params.splat;
 if (Array.isArray(pathParts)) {
 const fullPath = pathParts.join('/');
 }
});

Missing Error Handlers

Ensure error-handling middleware is configured:

app.use((err, req, res, next) => {
 console.error(err.stack);
 res.status(err.status || 500).json({
 error: err.message || 'Internal Server Error'
 });
});

Body Parser Configuration

The changed default for express.urlencoded():

app.use(express.urlencoded({ extended: true })); // If you need rich objects

Dotfile Access

Explicit configuration for dot-directories:

app.use('/.well-known', express.static('public/.well-known', {
 dotfiles: 'allow'
}));

Testing Strategies

Unit Tests

Update tests that check for deprecated behaviors:

test('returns 404 for unknown routes', async () => {
 const response = await request(app).get('/nonexistent');
 expect(response.status).toBe(404);
});

Integration Tests

Test complete request-response cycles:

test('handles async errors', async () => {
 app.get('/error', async () => {
 throw new Error('test error');
 });
 const response = await request(app).get('/error');
 expect(response.status).toBe(500);
});

Load Testing

Verify performance hasn't degraded:

autocannon -c 100 -d 30 http://localhost:3000/api endpoints

Following comprehensive trunk-based development practices ensures your testing strategy catches these issues before deployment.

Conclusion

Migrating to Express 5 is straightforward for most applications. The breaking changes are well-documented, automated codemods handle common updates, and the improvements--particularly automatic promise rejection handling--simplify your codebase.

Key to success: prepare by auditing dependencies, understand breaking changes, apply codemods, and test thoroughly. Most applications require modest changes to take advantage of Express 5's improvements.

For teams maintaining Express 4 applications, the migration investment pays dividends in code clarity, security, and future maintainability. Express 5 positions your application for continued success with modern Node.js features and ongoing framework support.

If you're exploring other JavaScript frameworks for your CMS needs, check out our guide on open source headless CMS options built with JavaScript. For implementing consistent patterns in your codebase, our guide on CSS naming conventions provides additional best practices.

Sources

1. Express.js Official Migration Guide - Comprehensive breaking changes documentation
2. Express.js v5 Release Announcement - Official release notes and rationale
3. @expressjs/codemod GitHub Repository - Automated migration tools