@whatwg-node/server

Minor Changes

• #3617 f78c03b Thanks @ardatan! - Stop exporting crypto from @whatwg-node/fetch (and from createFetch / FetchAPI). Use globalThis.crypto instead; it is available on all supported runtimes (Node.js >=22.15).

Minor Changes

• #3561 52a5bf6 Thanks @ardatan! - Drop support for Node.js 18 and 20. The minimum supported Node.js version is now 22.15.

Why

Node.js 18 and 20 are end-of-life and no longer receive security updates. Keeping them in our support matrix forced version-specific workarounds and slowed adoption of newer Node TLS APIs.

The floor is set to 22.15 (not just 22.0) so we can rely on tls.getCACertificates() (Node.js 22.15 / 23.10) and always-on zlib zstd helpers (createZstdCompress / createZstdDecompress, Node.js 22.15 / 23.8). That matches the oldest currently supported LTS line (22 Maintenance) while dropping only EOL majors.

SemVer

• 0.x packages: minor bump (breaking changes are allowed in minors while major is 0).

• 1.x packages (@whatwg-node/promise-helpers, @whatwg-node/server-plugin-cookies): major bump, since dropping supported Node versions is a breaking engines change for SemVer >=1.0.0 consumers.

What changed

• engines.node: all published packages now declare >=22.15.0 (including @whatwg-node/promise-helpers, which was still on >=16).

• @whatwg-node/events: removed. Native CustomEvent / Event / EventTarget are available on Node.js 22+, so the ponyfill is no longer maintained; use the platform globals.

• @whatwg-node/fetch: dropped the require("crypto").webcrypto fallback; crypto is always globalThis.crypto on supported runtimes.

• @whatwg-node/server: removed the Node 18 setHeaders workaround (isNode1x); ServerResponse#setHeaders is used whenever it exists.

• @whatwg-node/node-fetch: Runtime guards for zlib.createZstdCompress / createZstdDecompress are removed; zstd is always included in Accept-Encoding.

• CI / e2e: unit matrix is [22, 24, 26]; AWS Lambda runtime and Azure Function target moved from Node 20 to Node 22.

If you are still on Node 18 or 20, upgrade to Node.js 22.15+ (or 24 / 26) before installing this release.

• #1505 36ef02b Thanks @EmrysMyrddin! - Breaking Change: Remove deprecated handleNodeRequest in favor of handleNodeRequestAndResponse.

  adapter.handleNodeRequest(nodeRequest, ...ctx) is gone. Prefer handleNodeRequestAndResponse, which also receives the Node response so request normalization (abort wiring, etc.) can use it.

  Before:

  const response = await adapter.handleNodeRequest(req, { userId: "1" });

  After:

  const response = await adapter.handleNodeRequestAndResponse(req, res, {
    userId: "1",
  });

  Notes:

  • Pass the real ServerResponse / Http2ServerResponse (or a container with { raw: res }) as the second argument.

  • Like before, this returns a WHATWG Response and does not write it to res. Use adapter(req, res), adapter.requestListener, or adapter.handle(req, res) when you want the adapter to send the response.

• #3610 72dad02 Thanks @ardatan! - Add useLimitRequestBodySize to reject oversized request bodies early via Content-Length, and while streaming with a byte-counting TransformStream (so a short or missing Content-Length cannot bypass the limit).

  Optional responseFromError customizes the early-reject Response (e.g. GraphQL error JSON in Yoga).

  If you also use useContentEncoding, put it before useLimitRequestBodySize in the plugins array so the limit applies to decoded body bytes.

Patch Changes

• #3568 205d949 Thanks @ardatan! - Omit Access-Control-Allow-Origin when the request Origin is not in the allowlist, instead of sending the string null.

  Returning Access-Control-Allow-Origin: null is discouraged (MDN / W3C CORS for developers): the browser should simply not see an ACAO header and enforce the Same-Origin Policy.

  Browser coverage for this CORS behavior and for @whatwg-node/server-plugin-cookies is covered by Puppeteer tests (npm run test:browser).

• #3611 ebb2ab6 Thanks @ardatan! - Discard unread Node/uWS request bodies when responding (e.g. early endResponse), so keep-alive connections are not stalled and large rejected uploads are not buffered for the lifetime of the response.

• #3012 3e55abc Thanks @gmaclennan! - Destroy the Node response when the response body stream errors or is aborted, and propagate Readable.destroy(err) in the node-fetch stream ponyfill so piped sockets close with RST / ECONNRESET instead of hanging.

  Also make ponyfill ReadableStream.pipeTo() reject when the destination write fails (after aborting the writer), instead of resolving successfully.

• #3590 d3b2c17 Thanks @ardatan! - Fix native Request handling in the server adapter and pass the active fetch implementation to the request handler and plugins.

  When a request originated from the runtime's native Request implementation, the server adapter could still use the ponyfill/default Fetch API during later pipeline stages. That could lead to mismatched Request / Response constructors and inconsistent behavior across runtimes such as Node, Bun, and Deno. For example in Next.js, the incoming request object is the native Request while the returning Response object is ponyfilled which causes an error since Next.js expects it to be a native Response object. As a workaround, you had to provide fetchAPI: { Response } on your own. With this patch, this workaround is no longer needed.

  • Native Request instances are now detected correctly and routed through the matching runtime fetch API.

  • The request pipeline keeps using the correct Request, Response, and stream constructors for the active runtime.

  • useErrorHandling() now passes the resolved fetchAPI into custom error handlers so they can construct responses with the correct runtime primitives.

  • Request handlers now take fetchAPI as a third argument, so that you don't need to worry about which fetch implementation to take.

  createServerAdapter((request, context, fetchAPI) => fetchAPI.Response.json());

  This keeps adapter behavior consistent and avoids subtle incompatibilities when handling native requests or custom fetch implementations.

  It also avoids issues like this in GraphQL Yoga -> #4583 So that the TransformStream implementation given by fetchAPI will be compatible with the given request instance automatically.

• #3504 b4c83ab Thanks @ardatan! - Trim values when parsing Accept-Encoding / Content-Encoding header lists.

  Native HTTPS clients (e.g. undici) send values like br, gzip, deflate; without trimming, encodings after the first comma never matched and response compression was skipped.