From 4aacff777c82b7451756692b19ff0e8ded946bc3 Mon Sep 17 00:00:00 2001 From: vibhor-aggr Date: Sun, 12 Jul 2026 01:01:51 +0530 Subject: [PATCH] docs: clarify fetch class compatibility --- README.md | 7 ++++-- docs/docs/api/GlobalInstallation.md | 23 +++++++++++-------- .../best-practices/undici-vs-builtin-fetch.md | 6 ++++- docs/docs/index.md | 7 ++++-- 4 files changed, 29 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index e5a779c4bb6..3a4b5f0af2e 100644 --- a/README.md +++ b/README.md @@ -241,8 +241,11 @@ await fetch('https://example.com', { installs undici's `WebSocket`, `CloseEvent`, `ErrorEvent`, `MessageEvent`, and `EventSource` globals. -Avoid mixing a global `FormData` with `undici.fetch()`, or `undici.FormData` -with the built-in global `fetch()`. +Avoid mixing `fetch`, `Request`, `Response`, `Headers`, and `FormData` +implementations from different sources. For example, a `Request` created by +Node.js' built-in global `Request` is not guaranteed to work with `fetch` +imported from a different `undici` package version, and the reverse is also +unsupported. ### Version Compatibility diff --git a/docs/docs/api/GlobalInstallation.md b/docs/docs/api/GlobalInstallation.md index f50504a375d..fa912ecd2a6 100644 --- a/docs/docs/api/GlobalInstallation.md +++ b/docs/docs/api/GlobalInstallation.md @@ -72,11 +72,11 @@ const ws = new WebSocket('wss://example.com') const eventSource = new EventSource('https://example.com/events') ``` -### Pairing `fetch` and `FormData` +### Pairing fetch classes -When a request body is a `FormData` instance, the `fetch` and `FormData` -implementations must come from the same source. After `install()`, both globals -resolve to undici, so they always match: +When a request uses `Request`, `Response`, `Headers`, or `FormData` instances, +the fetch function and those classes should come from the same implementation. +After `install()`, the globals resolve to undici, so they always match: ```mjs import { install } from 'undici' @@ -87,19 +87,24 @@ const body = new FormData() await fetch('https://example.com', { method: 'POST', body }) ``` -If global installation is not desired, import the matching pair directly from -`'undici'` instead: +If global installation is not desired, import the matching classes directly +from `'undici'` instead: ```mjs -import { fetch, FormData } from 'undici' +import { fetch, FormData, Request } from 'undici' const body = new FormData() -await fetch('https://example.com', { method: 'POST', body }) +const request = new Request('https://example.com', { method: 'POST', body }) +await fetch(request) ``` Mixing a global `FormData` with `undici.fetch()`, or `undici.FormData` with the built-in global `fetch()`, can produce surprising multipart behavior across -Node.js and undici versions. Keep the two paired. +Node.js and undici versions. The same rule applies to `Request`, `Response`, and +`Headers`: a `Request` created by Node.js' built-in global `Request` is not +guaranteed to work with `fetch` imported from a different `undici` package +version, and an `undici.Request` is not guaranteed to work with the built-in +global `fetch()`. Use one implementation consistently. ### Conditional installation diff --git a/docs/docs/best-practices/undici-vs-builtin-fetch.md b/docs/docs/best-practices/undici-vs-builtin-fetch.md index 42ce9e10d36..f3794c5ae77 100644 --- a/docs/docs/best-practices/undici-vs-builtin-fetch.md +++ b/docs/docs/best-practices/undici-vs-builtin-fetch.md @@ -106,7 +106,11 @@ await fetch('https://example.com', { ``` Those combinations may behave differently across Node.js and undici versions. -Using matching pairs keeps multipart handling predictable. +The same rule applies to `Request`, `Response`, and `Headers`: objects created +by Node.js' built-in globals are not guaranteed to interoperate with `fetch` +imported from a different `undici` package version, and the reverse is also +unsupported. Use one implementation consistently, or call `install()` once at +process startup if globals are required. ## When you do NOT need to install undici diff --git a/docs/docs/index.md b/docs/docs/index.md index b1085611ad5..9811dbc8e52 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -243,8 +243,11 @@ await fetch('https://example.com', { installs undici's `WebSocket`, `CloseEvent`, `ErrorEvent`, `MessageEvent`, and `EventSource` globals. -Avoid mixing a global `FormData` with `undici.fetch()`, or `undici.FormData` -with the built-in global `fetch()`. +Avoid mixing `fetch`, `Request`, `Response`, `Headers`, and `FormData` +implementations from different sources. For example, a `Request` created by +Node.js' built-in global `Request` is not guaranteed to work with `fetch` +imported from a different `undici` package version, and the reverse is also +unsupported. ### Version Compatibility