{ "type": "module", "source": "doc/api/api-globalinstallation.md", "modules": [ { "textRaw": "Global Installation", "name": "global_installation", "type": "module", "desc": "

Undici provides an install() function to add fetch-related and other web API classes to globalThis, making them available globally without requiring imports.

", "methods": [ { "textRaw": "`install()`", "name": "install", "type": "method", "signatures": [ { "params": [] } ], "desc": "

Install undici's global web APIs on globalThis.

\n

Example:

\n
import { install } from 'undici'\n\n// Install undici's global web APIs\ninstall()\n\n// Now you can use fetch classes globally without importing\nconst response = await fetch('https://api.example.com/data')\nconst data = await response.json()\n\n// All classes are available globally:\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": "Installed Classes", "name": "installed_classes", "type": "module", "desc": "

The install() function adds the following classes to globalThis:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ClassDescription
fetchThe fetch function for making HTTP requests
HeadersHTTP headers management
ResponseHTTP response representation
RequestHTTP request representation
FormDataForm data handling
WebSocketWebSocket client
CloseEventWebSocket close event
ErrorEventWebSocket error event
MessageEventWebSocket message event
EventSourceServer-sent events client
", "displayName": "Installed Classes" }, { "textRaw": "Using `FormData` with `fetch`", "name": "using_`formdata`_with_`fetch`", "type": "module", "desc": "

If you send a FormData body, use matching implementations for fetch and\nFormData.

\n

These two patterns are safe:

\n
// Built-in globals from Node.js\nconst body = new FormData()\nawait fetch('https://example.com', {\n  method: 'POST',\n  body\n})\n
\n
// Globals installed from the undici package\nimport { install } from 'undici'\n\ninstall()\n\nconst body = new FormData()\nawait fetch('https://example.com', {\n  method: 'POST',\n  body\n})\n
\n

After install(), fetch, Headers, Response, Request, and FormData\nall come from the installed undici package, so they work as a matching set.\nWebSocket, CloseEvent, ErrorEvent, MessageEvent, and EventSource\nalso come from the installed undici package.

\n

If you do not want to install globals, import both from undici instead:

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

Avoid mixing a global FormData with undici.fetch(), or undici.FormData\nwith the built-in global fetch(). Keeping them paired avoids surprising\nmultipart behavior across Node.js and undici versions.

", "displayName": "Using `FormData` with `fetch`" }, { "textRaw": "Use Cases", "name": "use_cases", "type": "module", "desc": "

Global installation is useful for:

\n", "displayName": "Use Cases" }, { "textRaw": "Example: Polyfilling an Environment", "name": "example:_polyfilling_an_environment", "type": "module", "desc": "
import { install } from 'undici'\n\n// Check if fetch is available and install if needed\nif (typeof globalThis.fetch === 'undefined') {\n  install()\n  console.log('Undici fetch installed globally')\n}\n\n// Now fetch is guaranteed to be available\nconst response = await fetch('https://api.example.com')\n
", "displayName": "Example: Polyfilling an Environment" }, { "textRaw": "Example: Testing Environment", "name": "example:_testing_environment", "type": "module", "desc": "
import { install } from 'undici'\n\n// In test setup, ensure consistent fetch behavior\ninstall()\n\n// Now all tests use undici's implementations\ntest('fetch API test', async () => {\n  const response = await fetch('https://example.com')\n  expect(response).toBeInstanceOf(Response)\n})\n
", "displayName": "Example: Testing Environment" }, { "textRaw": "Notes", "name": "notes", "type": "module", "desc": "", "displayName": "Notes" } ], "displayName": "Global Installation" } ] }