Undici — High-Performance HTTP Client for Node.js

Introduction

Undici is the official HTTP/1.1 client maintained by the Node.js project. It was written from scratch to replace the legacy http module internals, delivering higher throughput and lower latency through a custom-built HTTP parser (llhttp) and connection pooling. Starting with Node.js 18, Undici powers the built-in global fetch implementation.

What Undici Does

• Provides a modern, Promise-based API for making HTTP/1.1 requests from Node.js
• Manages connection pools automatically with configurable keep-alive and pipelining
• Powers the built-in fetch() and WebSocket globals in Node.js 18+
• Supports interceptors, retries, redirects, and proxy connections
• Implements the WHATWG Fetch, Request, Response, and Headers APIs

Architecture Overview

Undici uses llhttp (a C-based HTTP parser compiled to WebAssembly) for fast header and body parsing. Connections are managed via a Pool or BalancedPool that maintains persistent sockets with HTTP keep-alive. Request dispatching is handled through a Dispatcher interface that supports middleware-like interceptors. The streaming body is consumed via async iterables for memory-efficient processing.

Self-Hosting & Configuration

• Install with npm install undici or use the built-in fetch in Node.js 18+
• Create a Pool with new Pool('https://api.example.com', { connections: 10 }) for connection reuse
• Configure retries with the RetryAgent for automatic retry on transient failures
• Set up a ProxyAgent with new ProxyAgent('http://proxy:8080') for proxy support
• Use interceptors to add auth headers, logging, or caching to all requests

Key Features

• Written from scratch for Node.js with no dependency on the legacy http module
• HTTP pipelining support sends multiple requests on a single connection
• Pool and BalancedPool for automatic connection management and load distribution
• MockAgent for testing: intercept and mock HTTP requests without network access
• Streams and async iterables for efficient handling of large response bodies

Comparison with Similar Tools

• node-fetch — polyfill for Fetch API; Undici is the official implementation powering Node.js built-in fetch
• Axios — higher-level with interceptors; Undici is lower-level with better raw performance
• Got — feature-rich with retry and pagination; Undici focuses on protocol-level speed
• ky — browser-first fetch wrapper; Undici is Node.js-specific with connection pooling
• http module — legacy Node.js built-in; Undici replaces its internals with faster parsing

FAQ

Q: Is Undici the same as Node.js built-in fetch? A: Yes. The global fetch() in Node.js 18+ is powered by Undici under the hood.

Q: Does Undici support HTTP/2? A: Undici focuses on HTTP/1.1. For HTTP/2, use the built-in http2 module or a dedicated client.

Q: How do I mock HTTP requests in tests? A: Use MockAgent from Undici to intercept requests and return predetermined responses without hitting the network.

Q: Is Undici faster than Axios? A: Yes. Benchmarks show Undici achieves higher throughput due to its custom HTTP parser and connection pooling.

Sources

• https://github.com/nodejs/undici
• https://undici.nodejs.org