Differences from Express 5.3.0
So far the fork changes how Express is tested and built, not how it behaves: an app gets the same responses as on Express 5.3.0, except where 5.3.0 crashes the process or has a bug the fork fixes (see below). Bug fixes, speed-ups and strict TypeScript come next, on the same drop-in line (see the roadmap).
The full list is the "Unreleased (fork)" section of History.md.
Runtime
- Node.js 22, 24 and 26 only.
enginesis>= 22. Express 5.3.0 supports Node.js 18 and later. CI runs the three supported versions on Linux and Windows. - Our own copies of
router,send,serve-static,qsandbody-parser.router2.2.0,send1.2.1,serve-static2.2.1,qs6.17.1 andbody-parser2.4.0 are vendored intolib/router,lib/send,lib/serve-static,lib/qsandlib/body-parser, with their licences and test suites, so routing, file-sending, query-parsing and body-parsing bugs can be fixed in the fork. They're the same versions Express 5.3.0 installs, andexpress.staticnow uses the samesendasres.sendFileandres.download. The extended query parser andexpress.urlencoded({ extended: true })use ourqs, which needs no dependencies (it usesWeakMapandMapin place ofside-channel). See VENDORED.md. - A throwing
headerslistener no longer crashes the process. A bad value in theheadersoption ofres.sendFileorres.download(a CR or LF, or an invalid header name), or anexpress.staticsetHeadersfunction that throws, used to throw inside a file-stat callback and end the process on Express 5.3.0. The error now goes to the callback, or tonext(err)and the app's error handler. app.listen()doesn't swallow later server errors. Its startuperrorlistener is removed once the server is listening, so a latererrorreaches the app's listeners, or is thrown when there are none, as withhttp.createServer(). Express 5.3.0 silently dropped the first one.- Files that stat as 0 bytes but have content are sent. Linux
/procand/sysfiles go out whole throughres.sendFile,res.downloadandexpress.static, with noContent-Lengthand no ranges. Express 5.3.0 sent them empty. Really empty files are sent as before. - No per-request prototype swap on
app.listen()servers. The server makesreqandreswith the app's prototypes already set, soapp.handle()has nothing to swap. Apps see the same objects as before. The only visible difference: code that runs before the app on that server, such as anupgrade,connectorcheckContinuelistener, now getsreqandresthat already have the app's prototypes. res.sendsends binary bodies byte for byte. An ArrayBuffer, SharedArrayBuffer, DataView or any typed array is sent as the bytes it covers. Express 5.3.0 sent an ArrayBuffer as{}, a DataView as nothing, and aUint16ArrayorFloat64Arrayone byte per element, or answered 500.res.setkeeps an unknown Content-Type as given.res.set('Content-Type', 'custom-type')sendscustom-type, where Express 5.3.0 sentfalse.res.send,res.jsonandres.sendFilethen keep it too, where 5.3.0 used their default type.res.redirectsends no Content-Length with Transfer-Encoding, asres.sendalready did, so clients accept the response.res.cookiehonoursexpires: 0with amaxAge: the cookie getsMax-Ageand noExpires.res.jsonpfalls back to JSON when the callback name has no allowed characters, instead of sending JavaScript that doesn't parse.res.sendFileandres.downloadhonour a per-calletagoption. The app'setagsetting is only the default, and the options object you pass is no longer changed.res.renderafter another response no longer crashes the process. Without a callback, the "headers already sent" error goes to the error handler. Express 5.3.0 threw it from a deferred callback and ended the process.res.renderleaves its options object alone.res.localsis merged into a copy, so a frozen options object works and a shared one isn't changed.- A view name ending in
.gets the usual lookup error through the callback, where Express 5.3.0 threw arequire('')error synchronously. - View extensions match engines whatever their case. An engine registered as
HTMLrendersuser.html; Express 5.3.0 missed it and triedrequire('html'). An engine registered in the same case still wins,app.engineskeeps the keys as registered, and file names keep their case. res.linkswith nothing to add leaves theLinkheader alone.res.links({})sends noLinkheader, and a relation given an empty array adds no entry. Express 5.3.0 sent an emptyLinkheader, or one ending in,.res.appendkeeps an existing empty header value. Afterres.set('X-A', ''),res.append('X-A', 'b')sends both values, as two header lines. Express 5.3.0 replaced the empty value.res.redirectnames a status without a standard message by its number.res.redirect(399, '/next')says399. Redirecting to /next, where Express 5.3.0 saidundefined. Redirecting to /next.- A quoted
;in a type parameter stays in its value.normalizeType('text/plain; foo="a;b"')fromexpress/lib/utilsgivesfoo"a;b", where Express 5.3.0 gave"a. Responses don't change. - RegExp paths with
gorymatch on every request. In Express 5.3.0 such a RegExp kept itslastIndexbetween requests and matched only every other request, which let requests past a guard likeapp.use(/^\/admin/g, auth). The fork starts every match at index 0. - A mount path made only of slashes keeps its slashes. In Express 5.3.0,
app.use('//', router)(or///) matched every request, because the trailing slashes were trimmed to an empty path, so the router answered/secretbefore the app's own guards. In the fork a//mount answers only//and//followed by/..., andapp.get('//', ...)no longer answers/. - Mounting a router on itself at
/throws.router.use(router), or a cycle through other routers mounted at/, throws aTypeErrorat mount time. Express 5.3.0 accepts it, and any request the router doesn't answer then overflows the stack. Cycles through a mount at another path, which end, still work. - A
#fragment in the request target is dropped before routing. Node passes it through inreq.url, and Express 5.3.0 then parsed//user@host/admin#zas a URL with a host and routed/admin. The fork drops the fragment fromreq.urlandreq.originalUrlfirst, so a request is routed and read as if the fragment had not been sent. - A strict router's
''route answers its mount path. Withapp.use('/dir', express.Router({ strict: true })), the router'sget('')answersGET /dirand notGET /dir/. In Express 5.3.0 the strict router saw/for both, so a''route never matched. A route for/still answers both, as in 5.3.0. router.use(subApp)gives the caller its prototypes back. When a sub-app mounted withrouter.use()(or called as middleware inside another app) passes the request on,reqandresget the calling app's prototypes back, asapp.use()already did, so the middleware after it sees the caller'sreq.appand settings (trust proxy, for example). In Express 5.3.0 they kept the sub-app's. A bare router outside any app keeps the sub-app's, as before.- Userinfo in the
Hostheader is dropped. In Express 5.3.0,Host: admin.example:x@public.examplegavereq.hostnameadmin.example, which let a request past a host-based guard. The fork uses the host after the last@, for theHostheader and a trustedX-Forwarded-Host, and a host whose port is not all digits givesreq.hostandreq.hostnameundefined. - A trusted
X-Forwarded-Protois lowercased.HTTPSgivesreq.protocolhttpsandreq.securetrue. Express 5.3.0 kept the case, soreq.securewasfalse. - An IPv6 host has no subdomains.
Host: [::ffff:127.0.0.1]givesreq.subdomains[]. Express 5.3.0 split the address on its dots. - A trailing root dot is not a subdomain.
Host: tobi.ferrets.example.com.givesreq.subdomains["ferrets", "tobi"], as without the dot. Express 5.3.0 counted the empty label after it and gave["example", "ferrets", "tobi"]. - Fewer dependencies. The
merge-descriptors,onceandwrappypackages are gone, replaced by short built-in equivalents with the same behaviour. Withbody-parserandqsvendored,qsand the 18 packages it brought (side-channeland its chain) are gone too: a production install has 38 packages instead of 58. - Project links in
package.jsonpoint to the fork, and upstream'sfundingentry is removed. - Built-in TypeScript types. The package ships types ported from
@types/express5.0.6 and@types/express-serve-static-core5.1.3, so@types/expressis no longer needed and code written for it compiles unchanged. See Install the fork. - An ES module entry.
importloadsindex.mjs, a thin wrapper over the CommonJS build with the same named exports Node gives Express 5.3.0, soimportandrequireshare one copy of Express.package.jsonnow has anexportsmap; it keepsrequire('express'),require('express/lib/...')andrequire('express/package.json')working, and other paths inside the package can no longer be required.
Additions
Opt-in: an app that doesn't use them behaves as on Express 5.3.0.
- The
view enginessetting.app.set('view engines', ['pug', 'html'])letsres.render('page')renderpage.pugorpage.html, whichever exists first, after theview engineextension. A name with an extension that has no engine, such asuser.profile, gets one added. When nothing is found, the error lists the extensions tried. See Several template engines.
Tests that guard the drop-in promise
- Differential harness. Thousands of scenarios (143 written by hand and 3,306 generated from every
resmethod andreqproperty) run on Express 5.3.0 and on the fork, and must give byte-identical responses and error logs. The method comes from ultimate-express's test runner. - Ecosystem check. Ten popular middleware packages (body-parser, cors, helmet, morgan, cookie-parser, express-session, compression, multer, passport, express-rate-limit) run on both and must give byte-identical responses and log lines.
- Middleware's own test suites. The test suites of cors, express-session, multer, express-rate-limit, http-proxy-middleware, express-openapi-validator, express-fileupload, express-basic-auth, hpp and express-mongo-sanitize (1,678 tests) run against Express 5.3.0 and against the fork. Every test that passes on 5.3.0 must pass on the fork, and today all of them do.
- Security test suite. Checks that an auth guard always runs before the route it protects however the path is spelled, that CR and LF never inject a header, where redirects point, that no request pollutes
Object.prototype, and that file serving never leaves its root. - 100% coverage. Statements, branches, functions and lines of
lib/are measured with c8 and must stay at 100%, or CI fails. - Regression tests for 29 confirmed bugs. Each one asserts the correct behaviour and stays skipped until its fix lands.
- Upstream test PRs. Eight upstream test-coverage pull requests are ported, keeping their authors.
Tooling
- Biome is the only linter and formatter (no ESLint, no Prettier).
- A benchmark on every PR that changes code, against Express 5.3.0, Fastify, Koa, Hono, polka and plain
node:http. See Benchmarks. - Fewer installed packages for development: c8 replaces
nyc(137 packages), and Biome replaces ESLint (63 packages).