Fetch

undici implements the WHATWG Fetch Standard, providing fetch() together with the Request, Response, Headers, and FormData classes that mirror the browser APIs. The implementation follows the standard, so the MDN Fetch documentation applies as well.

import { fetch, Request, Response, Headers, FormData } from 'undici'

const response = await fetch('https://example.com')
const text = await response.text()

When mixing these classes, keep them from the same implementation: use the global fetch() with the global FormData, Request, Response, and Headers, and use undici's fetch() with undici's classes. Passing a value created by one implementation to the other can throw.

fetch(input, init?): Promise

Starts the process of fetching a resource from the network and returns a promise that fulfills with a <Response>. The promise rejects only on network failures; an HTTP error status such as 404 still fulfills the promise, so inspect response.ok to detect failures.

import { fetch } from 'undici'

const response = await fetch('https://example.com', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ hello: 'world' }),
})

console.log(response.status)
console.log(await response.json())

To route the request through a custom <Dispatcher> (for example a ProxyAgent or Agent with specific options), pass it as init.dispatcher.

import { fetch, Agent } from 'undici'

const response = await fetch('https://example.com', {
  dispatcher: new Agent({ connect: { rejectUnauthorized: false } }),
})

A set of key/value pairs representing form fields and their values, suitable for use as a fetch() request body. The implementation follows the WHATWG Fetch Standard; see the MDN FormData documentation.

When using FormData as a request body, keep fetch and FormData from the same implementation: use the global FormData with the global fetch(), and undici's FormData with undici's fetch().

new FormData(): void

Creates a new, empty FormData instance. Passing any argument other than undefined throws; in particular, an HTMLFormElement argument is not supported in this environment.

formData.append(name, value, filename?): void

Appends a new value to an existing key, or adds the key if it does not exist. Unlike formData.set(), append() keeps any existing values for name.

formData.delete(name): void

Deletes all values associated with name.

formData.get(name): string | File | null

formData.getAll(name): Array

formData.has(name): boolean

formData.set(name, value, filename?): void

Sets a new value for an existing key, or adds the key if it does not exist, replacing any values previously associated with name.

class Response extends BodyMixin

Represents the response to a request. Instances are typically obtained by awaiting fetch(), but can also be constructed directly. The implementation follows the WHATWG Fetch Standard; see the MDN Response documentation. Response inherits the body-reading methods described in Body mixin.

new Response(body?, init?): void

Creates a new Response.

Response.error(): Response

Returns a new Response representing a network error, with its type set to 'error'.

Response.json(data, init?): Response

import { Response } from 'undici'

const response = Response.json({ ok: true }, { status: 201 })

Response.redirect(url, status?): Response

response.clone(): Response

Creates a clone of the response. Throws a TypeError if the body has already been read or is locked.

class Request extends BodyMixin

Represents a resource request. Instances can be passed to fetch() in place of a URL string. The implementation follows the WHATWG Fetch Standard; see the MDN Request documentation. Request inherits the body-reading methods described in Body mixin.

new Request(input, init?): Request

Creates a new Request.

request.clone(): Request

Creates a clone of the request. Throws a TypeError if the body has already been read or is locked.

Represents the header list of a request or response and provides methods to read and modify it. The implementation follows the WHATWG Fetch Standard; see the MDN Headers documentation. Headers is iterable, yielding [name, value] pairs sorted by name.

new Headers(init?): void

Creates a new Headers object.

headers.append(name, value): void

Appends a value to a header, or adds the header if it does not exist. Existing values for name are preserved.

headers.delete(name): void

Removes the header named name.

headers.get(name): string | null

headers.has(name): boolean

headers.set(name, value): void

Sets a header to a single value, replacing any existing values for name.

headers.getSetCookie(): string

Returns each Set-Cookie header as a separate string, without combining them.

Request and Response both extend <BodyMixin>, which provides methods and properties for reading a body. Each consuming method reads the body once; after the body has been consumed, bodyUsed becomes true and calling another consuming method throws a TypeError.

body.arrayBuffer(): Promise

body.blob(): Promise

body.bytes(): Promise

body.formData(): Promise

Buffers and parses the entire body as multipart/form-data or application/x-www-form-urlencoded. Because multipart parsing has inherent security risks and the whole body is buffered, this method must only be called on responses from trusted servers.

For responses from untrusted or user-controlled servers, use a dedicated streaming parser such as @fastify/busboy and apply application-specific limits:

import { Busboy } from '@fastify/busboy'
import { Readable } from 'node:stream'

const response = await fetch('...')
const busboy = new Busboy({
  headers: { 'content-type': response.headers.get('content-type') },
})

// Handle the events emitted by `busboy`.

Readable.fromWeb(response.body).pipe(busboy)

body.json(): Promise

body.text(): Promise

body.textStream(): ReadableStream

An undici-specific extension that exposes the body as a stream of decoded text chunks rather than buffering it. It is not part of the WHATWG Fetch Standard.