projektuebersicht/node_modules/undici/docs/docs/best-practices/undici-vs-builtin-fetch.md

Undici Module vs. Node.js Built-in Fetch

Node.js has shipped a built-in fetch() implementation powered by undici since Node.js v18. This guide explains the relationship between the undici npm package and the built-in fetch, and when you should install one versus relying on the other.

Background

The fetch(), Request, Response, Headers, and FormData globals in Node.js v18+ are provided by a version of undici that is bundled into Node.js itself. You can check which version is bundled with:

console.log(process.versions.undici); // e.g., "7.5.0"

When you install undici from npm, you get the full library with all of its additional APIs, and potentially a newer release than what your Node.js version bundles.

Keep fetch and FormData from the same implementation

When you send a FormData body, keep fetch and FormData together from the same implementation.

Use one of these patterns:

Built-in globals

const body = new FormData()
body.set('name', 'some')
body.set('someOtherProperty', '8000')

await fetch('https://example.com', {
  method: 'POST',
  body
})

undici module imports

import { fetch, FormData } from 'undici'

const body = new FormData()
body.set('name', 'some')
body.set('someOtherProperty', '8000')

await fetch('https://example.com', {
  method: 'POST',
  body
})

undici.install() globals

If you want the installed undici package to provide the globals, call install():

import { install } from 'undici'

install()

const body = new FormData()
body.set('name', 'some')
body.set('someOtherProperty', '8000')

await fetch('https://example.com', {
  method: 'POST',
  body
})

install() replaces the global fetch, Headers, Response, Request, and FormData implementations with undici's versions, and also installs undici's WebSocket, CloseEvent, ErrorEvent, MessageEvent, and EventSource globals.

Avoid mixing implementations in the same request, for example:

import { fetch } from 'undici'

const body = new FormData()

await fetch('https://example.com', {
  method: 'POST',
  body
})

import { FormData } from 'undici'

const body = new FormData()

await fetch('https://example.com', {
  method: 'POST',
  body
})

Those combinations may behave differently across Node.js and undici versions. Using matching pairs keeps multipart handling predictable.

When you do NOT need to install undici

If all of the following are true, you can rely on the built-in globals and skip adding undici to your dependencies:

• You only need the standard Fetch API (fetch, Request, Response, Headers, FormData).
• You are running Node.js v18 or later.
• You do not depend on features or bug fixes introduced in a version of undici newer than the one bundled with your Node.js release.
• You want zero additional runtime dependencies.
• You want cross-platform interoperability with browsers and other runtimes (Deno, Bun, Cloudflare Workers, etc.) using the same Fetch API surface.

This is common in applications that make straightforward HTTP requests or in libraries that target multiple JavaScript runtimes.

When you SHOULD install undici

Install undici from npm when you need capabilities beyond the standard Fetch API:

Advanced HTTP APIs

undici exposes request, stream, pipeline, and connect methods that provide lower-level control and significantly better performance than fetch:

import { request } from 'undici';

const { statusCode, headers, body } = await request('https://example.com');
const data = await body.json();

Connection pooling and dispatchers

Client, Pool, BalancedPool, Agent, and their configuration options let you manage connection lifecycle, keep-alive behavior, pipelining depth, and concurrency limits:

import { Pool } from 'undici';

const pool = new Pool('https://example.com', { connections: 10 });
const { body } = await pool.request({ path: '/', method: 'GET' });

Proxy support

ProxyAgent and EnvHttpProxyAgent handle HTTP(S) proxying. Note that Node.js v22.21.0+ and v24.0.0+ support environment-variable-based proxy configuration for the built-in fetch via the --use-env-proxy flag (or NODE_USE_ENV_PROXY=1). However, undici's ProxyAgent still provides programmatic control through the dispatcher API:

import { ProxyAgent, fetch } from 'undici';

const proxyAgent = new ProxyAgent('https://my-proxy.example.com:8080');
const response = await fetch('https://example.com', { dispatcher: proxyAgent });

Testing and mocking

MockAgent, MockClient, and MockPool let you intercept and mock HTTP requests without patching globals or depending on external libraries:

import { MockAgent, setGlobalDispatcher, fetch } from 'undici';

const mockAgent = new MockAgent();
setGlobalDispatcher(mockAgent);

const pool = mockAgent.get('https://example.com');
pool.intercept({ path: '/api' }).reply(200, { message: 'mocked' });

Interceptors and middleware

Custom dispatchers and interceptors (retry, redirect, cache, DNS) give you fine-grained control over how requests are processed.

Newer version than what Node.js bundles

The npm package often includes features, performance improvements, and bug fixes that have not yet landed in a Node.js release. If you need a specific fix or feature, you can install a newer version directly.

Version compatibility

Node.js version	Bundled undici version	Notes
v18.x	~5.x	fetch is experimental (behind --experimental-fetch in early v18)
v20.x	~6.x	fetch is stable
v22.x	~6.x / ~7.x	fetch is stable
v24.x	~7.x	fetch is stable; env-proxy support via --use-env-proxy

You can always check the exact bundled version at runtime with process.versions.undici.

Installing undici from npm does not replace the built-in globals. If you want your installed version to replace the global fetch and related classes, use install(). Otherwise, import fetch directly from 'undici':

import { fetch } from 'undici' // uses your installed version, not the built-in

Further reading

• API Reference: Fetch
• API Reference: Client
• API Reference: Pool
• API Reference: ProxyAgent
• API Reference: MockAgent
• API Reference: Global Installation