File Explorer

1# Global Installation2 3Undici provides an `install()` function to add all WHATWG fetch classes to `globalThis`, making them available globally without requiring imports.4 5## `install()`6 7Install all WHATWG fetch classes globally on `globalThis`.8 9**Example:**10 11```js12import { install } from 'undici'13 14// Install all WHATWG fetch classes globally  15install()16 17// Now you can use fetch classes globally without importing18const response = await fetch('https://api.example.com/data')19const data = await response.json()20 21// All classes are available globally:22const headers = new Headers([['content-type', 'application/json']])23const request = new Request('https://example.com')24const formData = new FormData()25const ws = new WebSocket('wss://example.com')26const eventSource = new EventSource('https://example.com/events')27```28 29## Installed Classes30 31The `install()` function adds the following classes to `globalThis`:32 33| Class | Description |34|-------|-------------|35| `fetch` | The fetch function for making HTTP requests |36| `Headers` | HTTP headers management |37| `Response` | HTTP response representation |38| `Request` | HTTP request representation |39| `FormData` | Form data handling |40| `WebSocket` | WebSocket client |41| `CloseEvent` | WebSocket close event |42| `ErrorEvent` | WebSocket error event |43| `MessageEvent` | WebSocket message event |44| `EventSource` | Server-sent events client |45 46## Using `FormData` with `fetch`47 48If you send a `FormData` body, use matching implementations for `fetch` and49`FormData`.50 51These two patterns are safe:52 53```js54// Built-in globals from Node.js55const body = new FormData()56await fetch('https://example.com', {57  method: 'POST',58  body59})60```61 62```js63// Globals installed from the undici package64import { install } from 'undici'65 66install()67 68const body = new FormData()69await fetch('https://example.com', {70  method: 'POST',71  body72})73```74 75After `install()`, `fetch`, `Headers`, `Response`, `Request`, and `FormData`76all come from the installed `undici` package, so they work as a matching set.77 78If you do not want to install globals, import both from `undici` instead:79 80```js81import { fetch, FormData } from 'undici'82 83const body = new FormData()84await fetch('https://example.com', {85  method: 'POST',86  body87})88```89 90Avoid mixing a global `FormData` with `undici.fetch()`, or `undici.FormData`91with the built-in global `fetch()`. Keeping them paired avoids surprising92multipart behavior across Node.js and undici versions.93 94## Use Cases95 96Global installation is useful for:97 98- **Polyfilling environments** that don't have native fetch support99- **Ensuring consistent behavior** across different Node.js versions100- **Library compatibility** when third-party libraries expect global fetch101- **Migration scenarios** where you want to replace built-in implementations102- **Testing environments** where you need predictable fetch behavior103 104## Example: Polyfilling an Environment105 106```js107import { install } from 'undici'108 109// Check if fetch is available and install if needed110if (typeof globalThis.fetch === 'undefined') {111  install()112  console.log('Undici fetch installed globally')113}114 115// Now fetch is guaranteed to be available116const response = await fetch('https://api.example.com')117```118 119## Example: Testing Environment120 121```js122import { install } from 'undici'123 124// In test setup, ensure consistent fetch behavior125install()126 127// Now all tests use undici's implementations128test('fetch API test', async () => {129  const response = await fetch('https://example.com')130  expect(response).toBeInstanceOf(Response)131})132```133 134## Notes135 136- The `install()` function overwrites any existing global implementations137- Classes installed are undici's implementations, not Node.js built-ins138- This provides access to undici's latest features and performance improvements139- The global installation persists for the lifetime of the process