{ "type": "module", "source": "doc/api/best-practices-undici-vs-builtin-fetch.md", "modules": [ { "textRaw": "Undici Module vs. Node.js Built-in Fetch", "name": "undici_module_vs._node.js_built-in_fetch", "type": "module", "desc": "

Node.js has shipped a built-in fetch() implementation powered by undici since\nNode.js v18. This guide explains the relationship between the undici npm\npackage and the built-in fetch, and when you should install one versus relying\non the other.

", "modules": [ { "textRaw": "Background", "name": "background", "type": "module", "desc": "

The fetch(), Request, Response, Headers, and FormData globals in\nNode.js v18+ are provided by a version of undici that is bundled into Node.js\nitself. You can check which version is bundled with:

\n
console.log(process.versions.undici); // e.g., \"7.5.0\"\n
\n

When you install undici from npm, you get the full library with all of its\nadditional APIs, and potentially a newer release than what your Node.js version\nbundles.

", "displayName": "Background" }, { "textRaw": "Keep `fetch` and `FormData` from the same implementation", "name": "keep_`fetch`_and_`formdata`_from_the_same_implementation", "type": "module", "desc": "

When you send a FormData body, keep fetch and FormData together from the\nsame implementation.

\n

Use one of these patterns:

", "modules": [ { "textRaw": "Built-in globals", "name": "built-in_globals", "type": "module", "desc": "
const body = new FormData()\nbody.set('name', 'some')\nbody.set('someOtherProperty', '8000')\n\nawait fetch('https://example.com', {\n  method: 'POST',\n  body\n})\n
", "displayName": "Built-in globals" }, { "textRaw": "`undici` module imports", "name": "`undici`_module_imports", "type": "module", "desc": "
import { fetch, FormData } from 'undici'\n\nconst body = new FormData()\nbody.set('name', 'some')\nbody.set('someOtherProperty', '8000')\n\nawait fetch('https://example.com', {\n  method: 'POST',\n  body\n})\n
", "displayName": "`undici` module imports" }, { "textRaw": "`undici.install()` globals", "name": "`undici.install()`_globals", "type": "module", "desc": "

If you want the installed undici package to provide the globals, call\ninstall():

\n
import { install } from 'undici'\n\ninstall()\n\nconst body = new FormData()\nbody.set('name', 'some')\nbody.set('someOtherProperty', '8000')\n\nawait fetch('https://example.com', {\n  method: 'POST',\n  body\n})\n
\n

install() replaces the global fetch, Headers, Response, Request, and\nFormData implementations with undici's versions, and also installs undici's\nWebSocket, CloseEvent, ErrorEvent, MessageEvent, and EventSource\nglobals.

\n

Avoid mixing implementations in the same request, for example:

\n
import { fetch } from 'undici'\n\nconst body = new FormData()\n\nawait fetch('https://example.com', {\n  method: 'POST',\n  body\n})\n
\n
import { FormData } from 'undici'\n\nconst body = new FormData()\n\nawait fetch('https://example.com', {\n  method: 'POST',\n  body\n})\n
\n

Those combinations may behave differently across Node.js and undici versions.\nUsing matching pairs keeps multipart handling predictable.

", "displayName": "`undici.install()` globals" } ], "displayName": "Keep `fetch` and `FormData` from the same implementation" }, { "textRaw": "When you do NOT need to install undici", "name": "when_you_do_not_need_to_install_undici", "type": "module", "desc": "

If all of the following are true, you can rely on the built-in globals and skip\nadding undici to your dependencies:

\n\n

This is common in applications that make straightforward HTTP requests or in\nlibraries that target multiple JavaScript runtimes.

", "displayName": "When you do NOT need to install undici" }, { "textRaw": "When you SHOULD install undici", "name": "when_you_should_install_undici", "type": "module", "desc": "

Install undici from npm when you need capabilities beyond the standard Fetch API:

", "modules": [ { "textRaw": "Advanced HTTP APIs", "name": "advanced_http_apis", "type": "module", "desc": "

undici exposes request, stream, pipeline, and connect methods that\nprovide lower-level control and significantly better performance than fetch:

\n
import { request } from 'undici';\n\nconst { statusCode, headers, body } = await request('https://example.com');\nconst data = await body.json();\n
", "displayName": "Advanced HTTP APIs" }, { "textRaw": "Connection pooling and dispatchers", "name": "connection_pooling_and_dispatchers", "type": "module", "desc": "

Client, Pool, BalancedPool, Agent, and their configuration options\nlet you manage connection lifecycle, keep-alive behavior, pipelining depth,\nand concurrency limits:

\n
import { Pool } from 'undici';\n\nconst pool = new Pool('https://example.com', { connections: 10 });\nconst { body } = await pool.request({ path: '/', method: 'GET' });\n
", "displayName": "Connection pooling and dispatchers" }, { "textRaw": "Proxy support", "name": "proxy_support", "type": "module", "desc": "

ProxyAgent and EnvHttpProxyAgent handle HTTP(S) proxying. Note that\nNode.js v22.21.0+ and v24.0.0+ support environment-variable-based proxy\nconfiguration for the built-in fetch via the --use-env-proxy flag (or\nNODE_USE_ENV_PROXY=1). However, undici's ProxyAgent still provides\nprogrammatic control through the dispatcher API:

\n
import { ProxyAgent, fetch } from 'undici';\n\nconst proxyAgent = new ProxyAgent('https://my-proxy.example.com:8080');\nconst response = await fetch('https://example.com', { dispatcher: proxyAgent });\n
", "displayName": "Proxy support" }, { "textRaw": "Testing and mocking", "name": "testing_and_mocking", "type": "module", "desc": "

MockAgent, MockClient, and MockPool let you intercept and mock HTTP\nrequests without patching globals or depending on external libraries:

\n
import { MockAgent, setGlobalDispatcher, fetch } from 'undici';\n\nconst mockAgent = new MockAgent();\nsetGlobalDispatcher(mockAgent);\n\nconst pool = mockAgent.get('https://example.com');\npool.intercept({ path: '/api' }).reply(200, { message: 'mocked' });\n
", "displayName": "Testing and mocking" }, { "textRaw": "Interceptors and middleware", "name": "interceptors_and_middleware", "type": "module", "desc": "

Custom dispatchers and interceptors (retry, redirect, cache, DNS) give you\nfine-grained control over how requests are processed.

", "displayName": "Interceptors and middleware" }, { "textRaw": "Newer version than what Node.js bundles", "name": "newer_version_than_what_node.js_bundles", "type": "module", "desc": "

The npm package often includes features, performance improvements, and bug fixes\nthat have not yet landed in a Node.js release. If you need a specific fix or\nfeature, you can install a newer version directly.

", "displayName": "Newer version than what Node.js bundles" } ], "displayName": "When you SHOULD install undici" }, { "textRaw": "Version compatibility", "name": "version_compatibility", "type": "module", "desc": "\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Node.js versionBundled undici versionNotes
v18.x~5.xfetch is experimental (behind --experimental-fetch in early v18)
v20.x~6.xfetch is stable
v22.x~6.x / ~7.xfetch is stable
v24.x~7.xfetch is stable; env-proxy support via --use-env-proxy
\n

You can always check the exact bundled version at runtime with\nprocess.versions.undici.

\n

Installing undici from npm does not replace the built-in globals. If you want\nyour installed version to replace the global fetch and related classes, use\ninstall(). Otherwise, import fetch\ndirectly from 'undici':

\n
import { fetch } from 'undici' // uses your installed version, not the built-in\n
", "displayName": "Version compatibility" }, { "textRaw": "Further reading", "name": "further_reading", "type": "module", "desc": "", "displayName": "Further reading" } ], "displayName": "Undici Module vs. Node.js Built-in Fetch" } ] }