undici

Undici is the HTTP/1.1 client that powers Node.js’s built-in fetch(), written from scratch by the Node.js core team rather than wrapping the legacy http module. It exposes both a low-level, high-throughput request/stream/pipeline/dispatch API and a spec-compliant fetch() implementation, giving developers fine-grained control over connection pooling, keep-alive, and timeouts without sacrificing standards compliance.

Beyond basic requests, undici ships production features out of the box: a Cache interceptor with pluggable stores, MockAgent for deterministic testing, ProxyAgent/Socks5ProxyAgent/EnvHttpProxyAgent for proxied traffic, retry and redirect handlers, WebSocket and EventSource clients, and HTTP/2 support via H2CClient. Because it has no runtime dependencies and is maintained inside the Node.js org, it tracks platform standards closely and is the reference implementation many other libraries build on.

What You Get

• A spec-compliant fetch() implementation plus low-level request, stream, pipeline, and dispatch APIs for maximum throughput
• Agent, Pool, BalancedPool, and RoundRobinPool dispatchers for fine-grained connection-pool and keep-alive configuration
• Built-in Cache interceptor with a pluggable MemoryCacheStore (and custom store support) that follows HTTP caching semantics
• MockAgent and SnapshotAgent for writing deterministic, network-free tests against real request/response shapes
• ProxyAgent, Socks5ProxyAgent, and EnvHttpProxyAgent for routing traffic through HTTP or SOCKS5 proxies
• Native WebSocket and EventSource client implementations, plus HTTP/2 support through H2CClient
• Composable interceptors (retry, redirect, dump, dns, decompress, deduplicate, cache) for building request middleware pipelines

Common Use Cases

• Replacing Node’s built-in http/https modules or node-fetch in server-side code that needs higher throughput and lower overhead
• Calling external APIs from a Node.js backend or serverless function with connection pooling and keep-alive tuned per host
• Mocking outbound HTTP calls in unit and integration tests via MockAgent instead of a separate network-mocking library
• Building an HTTP client with response caching (via the cache interceptor) for services that repeatedly hit the same upstream endpoints
• Routing outbound requests through corporate HTTP or SOCKS5 proxies in enterprise network environments

Under The Hood

Architecture — Undici is organized around a Dispatcher base class (lib/dispatcher/dispatcher-base.js) that Client, Pool, BalancedPool, RoundRobinPool, and Agent all extend; the top-level API methods (request, stream, pipeline, connect, upgrade) live in lib/api/ and are mixed onto Dispatcher.prototype in index.js. A single Client (lib/dispatcher/client.js, ~700 lines) owns one origin’s socket(s), tracking pending/running request queues via symbol-keyed internal state (kPending, kRunning, kQueue, kPipelining) and building the actual net/tls connection through buildConnector in lib/core/connect.js. Handlers (RetryHandler, RedirectHandler, DecoratorHandler) and composable interceptors (retry, redirect, cache, dns, decompress, deduplicate) wrap dispatch calls to add cross-cutting behavior without touching the core client, and MockAgent/SnapshotAgent in lib/mock/ implement the same Dispatcher interface so mocked and real traffic are interchangeable from the caller’s perspective.

Tech Stack — The package has zero runtime dependencies, deliberately reimplementing HTTP parsing, connection management, and even a WHATWG-compliant fetch/Headers/FormData/WebSocket/EventSource layer (lib/web/) on top of Node’s raw net/tls/http2 modules rather than depending on http. It requires Node.js >=22.19.0 and ships hand-written TypeScript declaration files (types/*.d.ts, checked with tsd) alongside the JavaScript source; the build pipeline uses esbuild to produce a bundled undici-fetch.js and a WASM build step for llhttp-based parsing (lib/llhttp/).

Code Quality — The test suite spans 409 files under test/ covering unit behavior, WPT (Web Platform Tests) conformance for fetch/WebSocket/EventSource, fuzzing, cache and cache-interceptor behavior, cookies, and Node’s own node:test runner integration, run via borp and c8 for coverage (configured in .c8rc.json against lib/**/*.js and index.js). Errors are centralized in lib/core/errors.js as named classes (e.g. InvalidArgumentError, ClientDestroyedError) rather than raw thrown strings, and internal state is consistently namespaced with Symbol() keys (kUrl, kConnect, kBusy, etc.) to avoid leaking private fields onto public prototypes.

API Design — The library deliberately offers two tiers: a low-level dispatch/request/stream/pipeline surface for teams that want maximum control and performance, and a drop-in, spec-compliant fetch() for teams that want Web-standard ergonomics with import { fetch } from 'undici'. Global installation via install() swaps in undici’s own fetch, Headers, Response, Request, FormData, and WebSocket, which keeps FormData/fetch pairing correct — a common footgun the docs call out explicitly. Getting started requires a single import and no configuration for the common path (await request(url)), while advanced features (proxies, caching, mocking, retries) are opt-in via constructor options or composable interceptors rather than being forced on every user.