npm install undici\nThe quickest way to get started is with fetch, which follows the\nFetch Standard and works the same way as\nthe browser API:
import { fetch } from 'undici'\n\nconst res = await fetch('https://example.com')\nconst data = await res.json()\nconsole.log(data)\nundici also exports a Request class that follows the Fetch Standard:
import { fetch, Request } from 'undici'\n\nconst req = new Request('https://example.com', {\n method: 'POST',\n headers: { 'content-type': 'application/json' },\n body: JSON.stringify({ hello: 'world' })\n})\nconst res = await fetch(req)\nconsole.log(res.status)\nres.body is a web ReadableStream. Use pipeline from\nnode:stream/promises to stream it to a file:
import { fetch } from 'undici'\nimport { pipeline } from 'node:stream/promises'\nimport { createWriteStream } from 'node:fs'\n\nconst res = await fetch('https://example.com/large-file.zip')\nawait pipeline(res.body, createWriteStream('./file.zip'))\n\n\nAlways consume or cancel the response body. In Node.js, garbage collection\nis not aggressive enough to release connections promptly, so leaving a body\nunread can cause connection leaks and stalled requests. See\nSpecification Compliance - Garbage Collection\nfor details.
\n
For more on fetch, see API Reference: Fetch.
By default, fetch, request, stream, and pipeline create a new connection\nfor each call. For applications that make many requests to the same origin,\nthis is wasteful. undici provides dispatchers that manage connections\ninternally.
Agent is the most general-purpose dispatcher. It pools connections per-origin\nand is the recommended default for most applications. Use it with\nsetGlobalDispatcher to affect all undici calls globally:
import { Agent, setGlobalDispatcher, fetch } from 'undici'\n\nconst agent = new Agent({\n keepAliveTimeout: 30_000,\n keepAliveMaxTimeout: 600_000\n})\nsetGlobalDispatcher(agent)\n\n// All subsequent fetch/request/stream/pipeline calls reuse connections\nconst res = await fetch('https://api.example.com/data')\nYou can also pass a dispatcher per-request:
\nawait fetch('https://api.example.com/data', { dispatcher: agent })\nPool manages a fixed set of connections to one origin. It gives you explicit\ncontrol over concurrency:
import { Pool, request } from 'undici'\n\nconst pool = new Pool('https://api.example.com', { connections: 10 })\n\nconst { body } = await request('https://api.example.com/data', {\n dispatcher: pool\n})\nconst data = await body.json()\n\npool.close()\nClient maps to a single TCP connection. It supports pipelining (sending\nmultiple requests before responses arrive):
import { Client } from 'undici'\n\nconst client = new Client('https://api.example.com', {\n pipelining: 5\n})\n\nconst { body } = await client.request({ path: '/', method: 'GET' })\nawait body.dump()\n\nclient.close()\nFor more on dispatcher options and lifecycle, see:
\n", "displayName": "`Client` — for a single connection" } ], "displayName": "Dispatchers: Connection reuse and pooling" }, { "textRaw": "Timeouts", "name": "timeouts", "type": "module", "desc": "undici applies timeouts at two levels:
\nheadersTimeout — time to wait for response headers (default: 300s).bodyTimeout — time between consecutive body chunks (default: 300s).Set these on the dispatcher or per-request:
\nimport { Agent, setGlobalDispatcher } from 'undici'\n\nconst agent = new Agent({\n headersTimeout: 5_000,\n bodyTimeout: 30_000\n})\n\nsetGlobalDispatcher(agent)\nTimeout errors are thrown as HeadersTimeoutError and BodyTimeoutError.\nSee API Reference: Errors for the full list.
undici exposes structured errors via error.code:
import { request, errors } from 'undici'\n\ntry {\n const { body } = await request('https://example.com')\n await body.json()\n} catch (err) {\n switch (err.code) {\n case 'UND_ERR_CONNECT_TIMEOUT':\n console.error('Connection timed out')\n break\n case 'UND_ERR_HEADERS_TIMEOUT':\n console.error('Headers timed out')\n break\n case 'UND_ERR_BODY_TIMEOUT':\n console.error('Body timed out')\n break\n case 'UND_ERR_ABORTED':\n console.error('Request was aborted')\n break\n default:\n console.error(err)\n }\n}\nimport { request } from 'undici'\n\nconst ac = new AbortController()\n\nsetTimeout(() => ac.abort(), 1000)\n\ntry {\n const { body } = await request('https://example.com', {\n signal: ac.signal\n })\n await body.dump()\n} catch (err) {\n console.error(err.code) // UND_ERR_ABORTED\n}\nUse ProxyAgent for HTTP(S) proxies, or EnvHttpProxyAgent to pick up\nproxy settings from environment variables:
import { ProxyAgent, setGlobalDispatcher } from 'undici'\n\nconst proxy = new ProxyAgent('http://proxy.internal:8080')\nsetGlobalDispatcher(proxy)\nSee Best Practices: Proxy and\nAPI Reference: ProxyAgent.
", "displayName": "Proxies" }, { "textRaw": "Mocking in tests", "name": "mocking_in_tests", "type": "module", "desc": "import { MockAgent, setGlobalDispatcher, request } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nconst mockPool = mockAgent.get('https://api.example.com')\nmockPool.intercept({ path: '/users' }).reply(200, [{ id: 1 }])\n\nconst { body } = await request('https://api.example.com/users')\nconsole.log(await body.json())\nSee Best Practices: Mocking Request\nand API Reference: MockAgent.
", "displayName": "Mocking in tests" }, { "textRaw": "Testing with undici", "name": "testing_with_undici", "type": "module", "desc": "For test suites, set short keep-alive timeouts to avoid slow teardowns:
\nimport { Agent, setGlobalDispatcher } from 'undici'\n\nconst agent = new Agent({\n keepAliveTimeout: 10,\n keepAliveMaxTimeout: 10\n})\nsetGlobalDispatcher(agent)\nSee Best Practices: Writing Tests.
", "displayName": "Testing with undici" }, { "textRaw": "Customizing the global fetch", "name": "customizing_the_global_fetch", "type": "module", "desc": "You can override Node.js's built-in globals with install():
import { install } from 'undici'\n\ninstall()\n\n// Global fetch, Headers, Response, Request, and FormData\n// now come from undici, not the Node.js bundle\nconst res = await fetch('https://example.com')\nSee API Reference: Global Installation.
", "displayName": "Customizing the global fetch" } ], "displayName": "Common patterns" }, { "textRaw": "Further reading", "name": "further_reading", "type": "module", "desc": "