upgrade-express

Upgrade Express 4 → 5

When to use

• The user asks to upgrade Express, or to move off Express 4 (in maintenance since 1 Apr 2025; EOL no sooner than 1 Oct 2026).
• legacy/express-4 applies and the user agrees to upgrade.

For a patch within 4.x, follow Safe maintenance in legacy/express-4 instead.

Before you start

• Read express, its middleware (body-parser, cors, helmet, express-session, multer, passport, routers, error wrappers) and Node from the lockfile and config. Express 5 needs Node ≥ 18; move to a supported LTS first if needed (upgrade-node).
• The working tree must be clean; work on a branch (chore/express-5).
• Ask the user:
  • whether codemods may edit files (they rewrite code; run them on a clean tree so the diff is reviewable);
  • whether network installs are approved (core/supply-chain cooldown applies);
  • which routes are business-critical, for the smoke test.
• Note: @expressjs/codemod on npm is deprecated; the official codemods now run through the codemod CLI from the codemod.com registry.

Steps

1. Baseline. Install from the lockfile and record lint, typecheck, tests and a manual hit on key routes. If the baseline fails, report it and ask before continuing.

2. Patch 4.x first (npm install express@^4.22.3) and make sure tests pass, so the major upgrade starts from the latest 4.x.

3. Inventory route patterns that change meaning in path-to-regexp 8:

   grep -rnE "\.(get|post|put|patch|delete|all|use|route)\(\s*['\"\`][^'\"\`]*[*?()+]" src
   

4. Run the codemods (review the diff after each run):

   npx codemod@latest @expressjs/v5-migration-recipe
   

   The recipe covers app.del → app.delete, req.param() → explicit req.params/req.body/req.query, res.send(status, body) and res.json(obj, status) → res.status().…, pluralized req.accepts*, res.sendfile → res.sendFile, res.redirect('back') and argument order, express.static.mime and dotfiles options. Individual codemods (@expressjs/route-del-to-delete, …) can be run one at a time the same way.

5. Upgrade the package: npm install express@^5 (and @types/express@^5 for TypeScript). Update middleware that pins Express 4 peers.

6. Fix route syntax by hand (codemods don't rewrite patterns):

   • /* → /*splat (or /{*splat} to also match the root); the matched value is an array;
   • /:file.:ext? → /:file{.:ext};
   • regex characters in strings ((, ), +, ?, [, ]) → arrays of paths or a RegExp;
   • app.use('*', …) / router.all('*', …) → '/*splat' or no path.

7. Behavior changes to check:

   • req.query uses the simple parser and is read-only. Code reading req.query.a.b or writing req.query.x = … must change; set app.set('query parser', 'extended') only if clients send nested queries, and validate the result.
   • req.body is undefined when no parser ran; add checks or schema validation instead of assuming {}.
   • Rejected promises now reach the error handler: remove express-async-handler/express-async-errors wrappers, and make sure the error handler handles those errors.
   • express.static ignores dotfiles by default; serve /.well-known explicitly if needed.
   • res.status() accepts only integers 100–999; res.clearCookie ignores maxAge/expires; req.host keeps the port.

8. Verify (next section). Show the diff summary and results; commit only when the user asks (git-commit skill). Then switch to backend/express.