# Undici — High-Performance HTTP Client for Node.js

> The official HTTP/1.1 client for Node.js, written from scratch to provide a faster, more correct, and fully featured alternative to the legacy http module.

## Install

Save in your project root:

# Undici — High-Performance HTTP Client for Node.js

## Quick Use
```bash
npm install undici
```
```javascript
import { request } from 'undici'

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

## 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

---
Source: https://tokrepo.com/en/workflows/asset-502f5739
Author: AI Open Source