`install()` replaces the global `fetch`, `Headers`, `Response`, `Request`, and

`FormData` implementations with undici's versions, so they all match. It also

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()`.

Undici provides an `install()` function to add fetch-related and other web API classes to `globalThis`, making them available globally:

import { install } from 'undici'

install()

When you call `install()`, these globals come from the same undici

implementation. For example, global `fetch` and global `FormData` will both be

undici's versions, and `WebSocket` and `EventSource` will also come from

undici, which is the recommended setup if you want to use undici through

globals.

This is useful for:

- Polyfilling environments that don't have fetch

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

Install undici's global web APIs on `globalThis`.

**Example:**

import { install } from 'undici'

install()

After `install()`, `fetch`, `Headers`, `Response`, `Request`, and `FormData`

all come from the installed `undici` package, so they work as a matching set.

`WebSocket`, `CloseEvent`, `ErrorEvent`, `MessageEvent`, and `EventSource`

also come from the installed `undici` package.

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

- The `install()` function overwrites any existing global implementations

- Classes installed are undici's implementations, not Node.js built-ins

- This provides access to undici's latest fetch, WebSocket, and EventSource features and performance improvements

- The global installation persists for the lifetime of the process

- **ignoreHeaders** `Array<String>` - Headers to ignore during request matching

- **excludeHeaders** `Array<String>` - Headers to exclude from snapshots (for security)

- **matchBody** `Boolean` - Whether to include request body in matching. Default: `true`

- **normalizeBody** `Function` - Optional function `(body) => string` to normalize the request body before matching (e.g. strip volatile fields like timestamps). Only used when `matchBody` is `true`.

- **matchQuery** `Boolean` - Whether to include query parameters in matching. Default: `true`

- **normalizeQuery** `Function` - Optional function `(query: URLSearchParams) => string` to normalize query parameters before matching (e.g. strip volatile params like cache-busters). Only used when `matchQuery` is `true`.

- **caseSensitive** `Boolean` - Whether header matching is case-sensitive. Default: `false`

- **shouldRecord** `Function` - Callback to determine if a request should be recorded

- **shouldPlayback** `Function` - Callback to determine if a request should be played back

By default (`matchBody: true`) the full request body string is included in the snapshot key. Set it to `false` to ignore the body entirely, or use `normalizeBody` to strip volatile fields (like timestamps) before matching:

const agent = new SnapshotAgent({

mode: 'playback',

snapshotPath: './snapshots.json',

// Match on everything except the timestamp field

normalizeBody: (body) => {

if (!body) return ''

const parsed = JSON.parse(String(body))

delete parsed.timestamp

return JSON.stringify(parsed)

}

})

`normalizeBody` receives the raw body (`string | Buffer | null | undefined`) and must return a `string`. It runs at both record and playback time so the hash is consistent. Two requests match the same snapshot whenever their normalized strings are identical.

Control which headers are used for request matching and what gets stored in snapshots:

RequestAbortedError

} = require('../core/errors')

const util = require('../core/util')

const { kBodyUsed } = require('../core/symbols')

const { addSignal, removeSignal } = require('./abort-signal')

function noop () {}

super({ autoDestroy: true })

this[kResume] = null

// Pipeline request bodies come from a live writable side and cannot be

// replayed across redirects or retries, even before any bytes are read.

this[kBodyUsed] = true

}

_read () {

const assert = require('node:assert')

const { AsyncResource } = require('node:async_hooks')

const { InvalidArgumentError, InvalidReturnValueError } = require('../core/errors')

const util = require('../core/util')

const { addSignal, removeSignal } = require('./abort-signal')

function noop () {}

function getWritableError (stream) {

return stream.errored ?? stream.writableErrored ?? stream._writableState?.errored

function createPrematureCloseError () {

const err = new Error('Premature close')

err.code = 'ERR_STREAM_PREMATURE_CLOSE'

return err

function trackWritableLifecycle (stream, callback) {

let done = false

const cleanup = () => {

stream.removeListener('close', onClose)

stream.removeListener('error', onError)

stream.removeListener('finish', onFinish)

}

const finish = (err, fromErrorEvent = false) => {

if (done) {

return

}

done = true

cleanup()

callback(err, fromErrorEvent)

}

const onClose = () => {

const err = getWritableError(stream)

finish(err ?? (!stream.writableFinished ? createPrematureCloseError() : undefined))

}

const onError = (err) => finish(err, true)

const onFinish = () => finish()

stream.on('close', onClose)

stream.on('error', onError)

stream.on('finish', onFinish)

if (stream.closed) {

process.nextTick(onClose)

} else if (stream.writableFinished) {

process.nextTick(onFinish)

}

class StreamHandler extends AsyncResource {

constructor (opts, factory, callback) {

if (!opts || typeof opts !== 'object') {

throw new InvalidReturnValueError('expected Writable')

}

trackWritableLifecycle(res, (err, fromErrorEvent) => {

const { callback, res, opaque, trailers, abort } = this

this.res = null

if (err || !res?.readable) {

util.destroy(res, fromErrorEvent ? undefined : err)

}

this.callback = null

this.runInAsyncScope(callback, null, err || null, { opaque, trailers })

if (err) {

abort(err)

}

})

kListeners: Symbol('listeners'),

kHTTPContext: Symbol('http context'),

kMaxConcurrentStreams: Symbol('max concurrent streams'),

kHostAuthority: Symbol('host authority'),

kHTTP2InitialWindowSize: Symbol('http2 initial window size'),

kHTTP2ConnectionWindowSize: Symbol('http2 connection window size'),

kEnableConnectProtocol: Symbol('http2session connect protocol'),

return !headerCharRegex.test(characters)

const rangeHeaderRegex = /^bytes (\d+)-(\d+)\/(\d+|\*)?$/

? {

start: parseInt(m[1]),

end: m[2] ? parseInt(m[2]) : null,

size: m[3] && m[3] !== '*' ? parseInt(m[3]) : null

}

: null

this.paused = true

socket.unshift(data)

} else {

throw this.createError(ret, data)

}

}

} catch (err) {

util.destroy(socket, err)

}

}

finish () {

assert(currentParser === null)

assert(this.ptr != null)

assert(!this.paused)

const { llhttp } = this

let ret

try {

currentParser = this

ret = llhttp.llhttp_finish(this.ptr)

} finally {

currentParser = null

}

if (ret === constants.ERROR.OK) {

return null

}

if (ret === constants.ERROR.PAUSED || ret === constants.ERROR.PAUSED_UPGRADE) {

this.paused = true

return null

}

return this.createError(ret, EMPTY_BUF)

}

createError (ret, data) {

const { llhttp, contentLength, bytesRead } = this

if (contentLength !== -1 && bytesRead !== contentLength) {

return new ResponseContentLengthMismatchError()

}

const ptr = llhttp.llhttp_get_error_reason(this.ptr)

let message = ''

if (ptr) {

const len = new Uint8Array(llhttp.memory.buffer, ptr).indexOf(0)

message =

'Response does not match the HTTP/1.1 protocol (' +

Buffer.from(llhttp.memory.buffer, ptr, len).toString() +

')'

}

return new HTTPParserError(message, constants.ERROR[ret], data)

}

destroy () {

assert(currentParser === null)

assert(this.ptr != null)

// On Mac OS, we get an ECONNRESET even if there is a full body to be forwarded

// to the user.

if (err.code === 'ECONNRESET' && parser.statusCode && !parser.shouldKeepAlive) {

const parserErr = parser.finish()

if (parserErr) {

this[kError] = parserErr

this[kClient][kOnError](parserErr)

}

return

}

const parser = this[kParser]

if (parser.statusCode && !parser.shouldKeepAlive) {

const parserErr = parser.finish()

if (parserErr) {

util.destroy(this, parserErr)

}

return

}

if (parser) {

if (!this[kError] && parser.statusCode && !parser.shouldKeepAlive) {

this[kError] = parser.finish() || this[kError]

}

this[kParser].destroy()

async function writeBlob (abort, body, client, request, socket, contentLength, header, expectsPayload) {

try {

if (contentLength != null && contentLength !== body.size) {

throw new RequestContentLengthMismatchError()