{ "type": "module", "source": "doc/api/api-globalinstallation.md", "modules": [ { "textRaw": "Global Installation", "name": "global_installation", "introduced_in": "v7.11.0", "type": "module", "stability": 2, "stabilityText": "Stable", "desc": "

undici ships its own implementations of several WHATWG web APIs. The install()\nfunction assigns those implementations onto globalThis, so they can be used\nwithout importing them from 'undici' first. This is useful for polyfilling\nenvironments, guaranteeing consistent behavior across Node.js versions, and\nsatisfying third-party libraries that expect the relevant classes to be global.

\n
import { install } from 'undici'\n\ninstall()\n\n// `fetch`, `Headers`, `Response`, `Request`, etc. now resolve to undici's\n// implementations.\nconst response = await fetch('https://example.com')\n
\n
const { install } = require('undici')\n\ninstall()\n
", "methods": [ { "textRaw": "`install()`", "name": "install", "type": "method", "meta": { "added": [ "v7.11.0" ], "changes": [] }, "signatures": [ { "params": [], "return": { "textRaw": "Returns: {undefined}", "name": "return", "type": "undefined" } } ], "desc": "

Overwrites the following properties of globalThis with undici's\nimplementations:

\n\n

Each installed value is the same object exported by 'undici' under the\nmatching name, so the global identifiers form a single, self-consistent set.\nThe assignment is unconditional: any pre-existing global of the same name,\nincluding the Node.js built-in, is replaced. The change persists for the\nlifetime of the process. Calling install() more than once is safe and simply\nre-assigns the same values.

\n

Documentation for each installed class lives on its own page: see\nfetch, WebSocket, and EventSource.

\n
import { install } from 'undici'\n\ninstall()\n\nconst headers = new Headers([['content-type', 'application/json']])\nconst request = new Request('https://example.com')\nconst formData = new FormData()\nconst ws = new WebSocket('wss://example.com')\nconst eventSource = new EventSource('https://example.com/events')\n
", "modules": [ { "textRaw": "Pairing `fetch` and `FormData`", "name": "pairing_`fetch`_and_`formdata`", "type": "module", "desc": "

When a request body is a FormData instance, the fetch and FormData\nimplementations must come from the same source. After install(), both globals\nresolve to undici, so they always match:

\n
import { install } from 'undici'\n\ninstall()\n\nconst body = new FormData()\nawait fetch('https://example.com', { method: 'POST', body })\n
\n

If global installation is not desired, import the matching pair directly from\n'undici' instead:

\n
import { fetch, FormData } from 'undici'\n\nconst body = new FormData()\nawait fetch('https://example.com', { method: 'POST', body })\n
\n

Mixing a global FormData with undici.fetch(), or undici.FormData with the\nbuilt-in global fetch(), can produce surprising multipart behavior across\nNode.js and undici versions. Keep the two paired.

", "displayName": "Pairing `fetch` and `FormData`" }, { "textRaw": "Conditional installation", "name": "conditional_installation", "type": "module", "desc": "

install() can be guarded so undici's fetch is only installed when no global\nfetch already exists:

\n
import { install } from 'undici'\n\nif (typeof globalThis.fetch === 'undefined') {\n  install()\n}\n\nconst response = await fetch('https://example.com')\n
", "displayName": "Conditional installation" } ] } ] } ] }