Skip to content

docs: document recent Express 5 and body-parser behavior in the API reference - #2576

Open
NopeCharon wants to merge 1 commit into
expressjs:mainfrom
NopeCharon:docs/5x-api-recent-releases
Open

NopeCharon wants to merge 1 commit into
expressjs:mainfrom
NopeCharon:docs/5x-api-recent-releases

Conversation

@NopeCharon

Copy link
Copy Markdown
Contributor

The 5.x API reference never picked up some behavior that shipped in Express 5.1.0–5.3.0 and body-parser 2.x. This PR documents it. I checked each change against the source and against a running express@5.3.0 / body-parser@2.4.0 app.

Page Change Shipped in
express.json(), .raw(), .text(), .urlencoded() Supported encodings now include br and zstd alongside gzip and deflate. zstd needs Node.js ^22.15.0 or >=23.8.0; older runtimes respond 415 body-parser 2.0.0 (br), 2.4.0 (zstd)
same An invalid limit (NaN, or a string bytes can't parse) now throws a TypeError when the middleware is created; null/undefined use the default body-parser 2.3.0
res.send() Uint8Array bodies are accepted and sent as application/octet-stream 5.1.0
res.send() Content-Length is skipped when Transfer-Encoding is already set 5.3.0
res.send() With a preset Content-Type, string bodies keep its parameters and get charset=utf-8 5.3.0
res.sendFile() The ETag header follows the app's etag setting (only false turns it off), and it is always a weak ETag 5.1.0
res.redirect() Deprecation warnings for a missing or non-string URL and a non-numeric status 5.2.0
req.fresh (4.x and 5.x) Freshness is only checked for GET, HEAD and QUERY requests with a 2xx/304 status. The 4.x page also notes that QUERY was added in 4.22.3 5.3.0, 4.22.3

The new Content-Disposition output from res.attachment() (content-disposition 2.x) is left out because #2551 already updates that example.

Validation

  • Ran a small Express 5.3.0 app that exercises every documented case: each content encoding, each limit value, Uint8Array bodies, preset Transfer-Encoding and Content-Type, sendFile with etag set to false and to "strong", res.redirect(undefined), and req.fresh for GET/HEAD/QUERY/POST. The observed headers and warnings match the text and examples.
  • npm run check (Prettier, ESLint, cspell) and npm run test:unit pass.
  • npm run build passes. In the generated HTML the new #options-for-etag-setting link resolves on the 5.x application page.

…eference

The 5.x API reference had not caught up with behavior shipped in Express
5.1.0 through 5.3.0 and in body-parser 2.x. Each item below was checked
against express@5.3.0 and body-parser@2.4.0.

express.json(), express.raw(), express.text(), express.urlencoded():
- List every supported Content-Encoding: br has been supported since
  body-parser 2.0.0, and zstd since 2.4.0 (Node.js ^22.15.0 or >=23.8.0;
  older runtimes reject zstd bodies with 415). The pages only listed
  gzip and deflate.
- Document that an invalid `limit` (NaN, or a string that bytes cannot
  parse) now throws a TypeError when the middleware is created, while
  null and undefined use the 100kb default (body-parser 2.3.0).

res.send():
- Accept Uint8Array bodies, which are sent as application/octet-stream
  like Buffers (5.1.0).
- Content-Length is not set when Transfer-Encoding is already present
  (5.3.0).
- With a preset Content-Type, string bodies keep the existing parameters
  and get charset=utf-8 (5.3.0).

res.sendFile():
- The ETag header follows the application's `etag` setting and is only
  turned off by app.set('etag', false); it is always a weak ETag based
  on file size and mtime (5.1.0).

res.redirect():
- Document the deprecation warnings emitted for a missing or non-string
  URL and a non-numeric status (5.2.0).

req.fresh (4.x and 5.x):
- Freshness is only checked for GET, HEAD and QUERY requests with a 2xx
  or 304 status. QUERY was added in 5.3.0 and 4.22.3; the 4.x page says
  which version, matching how that page notes other version-specific
  behavior.

Signed-off-by: NopeCharon <115794254+NopeCharon@users.noreply.github.com>
@NopeCharon
NopeCharon requested a review from a team as a code owner November 11, 2026 15:10
@netlify

netlify Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for expressjscom-preview ready!

Name Link
🔨 Latest commit fccbc5c
🔍 Latest deploy log https://app.netlify.com/projects/expressjscom-preview/deploys/6af485614dd499d9901b56c8
😎 Deploy Preview https://deploy-preview-2576--expressjscom-preview.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse
1 paths audited
Performance: 91 (🔴 down 6 from production)
Accessibility: 100 (no change from production)
Best Practices: 100 (no change from production)
SEO: 100 (no change from production)
PWA: 80 (no change from production)
View the detailed breakdown and full score reports
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant