Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Web APIs in Node.js

Node.js undici (the engine behind fetch)

How undici powers fetch() in Node.js: which web classes it provides, how to find its version, and what the npm package adds, such as Agent, Pool and MockAgent.

undici is the HTTP client that Node.js ships inside itself to implement fetch(). When you call the global fetch(), create a Request, Response, Headers or FormData, open a WebSocket or an EventSource, the code behind them is a bundled copy of undici. You cannot import 'undici' from this built-in copy: there is no public node:undici module.

The full library is also published on npm as undici. Installing it gives you the lower-level pieces that the built-in fetch() hides: Agent, Pool, Client, ProxyAgent, MockAgent, request(), stream() and pipeline(). On this site you cannot install packages, so the examples show the built-in part and the npm part is read-only.

NODE
console.log(process.versions.undici);   // the bundled undici version

Try it

Node.js What the bundled copy provides

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js fetch against a loopback server

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

The npm package is used like this (read-only here, because it must be installed):

JavaScript
import { Agent, setGlobalDispatcher, MockAgent, request } from 'undici';

// Tune connections for every fetch() in the process
setGlobalDispatcher(new Agent({ connections: 10, pipelining: 1, keepAliveTimeout: 10_000 }));

// A faster, lower-level client than fetch()
const { statusCode, body } = await request('https://example.com/data');
console.log(statusCode, await body.json());

// Fake responses in tests, without touching the network
const mock = new MockAgent();
mock.disableNetConnect();
mock.get('https://api.example.com').intercept({ path: '/users' }).reply(200, { users: [] });
setGlobalDispatcher(mock);
console.log(await (await fetch('https://api.example.com/users')).json());
Name Description
Agent Manages pools of connections per origin. Used by default for fetch().
Pool / Client Connections to one origin: many connections (Pool) or exactly one (Client).
ProxyAgent Sends requests through an HTTP proxy.
MockAgent Intercepts requests and returns canned replies, for tests.
setGlobalDispatcher(d) Replaces the dispatcher used by the global fetch().
request(), stream(), pipeline() Low-level APIs that skip the web Response machinery.

Errors: network failures surface from fetch() as TypeError: fetch failed with the real reason in err.cause.

Usage notes

  • Match the versions deliberately. The bundled copy and an installed undici are separate. Passing an Agent from a newer package to the built-in fetch() mostly works, but mixing versions can cause subtle differences; import fetch from the package too if you need an exact match.
  • setGlobalDispatcher() from the npm package also replaces what the global fetch() uses, through a well-known global symbol, which is how MockAgent captures built-in fetch() calls.
  • Keep-alive is on by default. Sockets stay open after a response, which makes later requests fast and can delay process exit or server shutdown in scripts.
  • Always consume or cancel the body. An unread response body holds its connection. Call await response.text(), response.body.cancel() or use AbortSignal.
  • Timeouts. The default connect and header timeouts are generous (300 seconds for headers). Use AbortSignal.timeout(ms) for per-request limits.
  • request() is quicker than fetch() for server-to-server calls because it avoids web-standard overhead, but its API differs from the browser.
  • Version. process.versions.undici shows which release your Node.js contains; it changes with Node.js releases.