{"id":13402439,"url":"https://github.com/nodejs/undici","last_synced_at":"2026-04-01T18:55:26.839Z","repository":{"id":36969980,"uuid":"133092972","full_name":"nodejs/undici","owner":"nodejs","description":"An HTTP/1.1 client, written from scratch for Node.js","archived":false,"fork":false,"pushed_at":"2026-03-29T00:07:11.000Z","size":14940,"stargazers_count":7473,"open_issues_count":319,"forks_count":731,"subscribers_count":51,"default_branch":"main","last_synced_at":"2026-03-29T02:58:03.125Z","etag":null,"topics":["client","http","nodejs"],"latest_commit_sha":null,"homepage":"https://nodejs.github.io/undici","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nodejs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":"MAINTAINERS.md","copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"nodejs","open_collective":"nodejs"}},"created_at":"2018-05-11T22:07:48.000Z","updated_at":"2026-03-28T21:24:43.000Z","dependencies_parsed_at":"2023-10-16T03:26:14.914Z","dependency_job_id":"f47ca4c0-4a14-4d56-8564-035b65a32fff","html_url":"https://github.com/nodejs/undici","commit_stats":{"total_commits":3265,"total_committers":289,"mean_commits":11.29757785467128,"dds":0.5430321592649311,"last_synced_commit":"54c5c6827c7d3f801bd72926234243a9ab8f7ef5"},"previous_names":["mcollina/undici"],"tags_count":257,"template":false,"template_full_name":null,"purl":"pkg:github/nodejs/undici","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodejs%2Fundici","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodejs%2Fundici/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodejs%2Fundici/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodejs%2Fundici/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nodejs","download_url":"https://codeload.github.com/nodejs/undici/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodejs%2Fundici/sbom","scorecard":{"id":632447,"data":{"date":"2025-08-21T07:58:17Z","repo":{"name":"github.com/nodejs/undici","commit":"80d5f321c5545b3b67f038f39ee135de4512dbee"},"scorecard":{"version":"v5.2.1","commit":"ab2f6e92482462fe66246d9e32f642855a691dc1"},"score":8.2,"checks":[{"name":"Security-Policy","score":9,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Warn: One or no descriptive hints of disclosure, vulnerability, and/or timelines in security policy","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#security-policy"}},{"name":"Dependency-Update-Tool","score":10,"reason":"update tool detected","details":["Info: detected update tool: Dependabot: .github/dependabot.yml:1"],"documentation":{"short":"Determines if the project uses a dependency update tool.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#dependency-update-tool"}},{"name":"Code-Review","score":10,"reason":"all changesets reviewed","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#code-review"}},{"name":"Maintained","score":10,"reason":"30 commit(s) and 15 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Info: jobLevel 'actions' permission set to 'read': .github/workflows/codeql.yml:31","Info: jobLevel 'contents' permission set to 'read': .github/workflows/codeql.yml:32","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/nodejs.yml:220","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/release-create-pr.yml:26","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/release.yml:46","Info: topLevel 'contents' permission set to 'read': .github/workflows/autobahn.yml:16","Warn: topLevel 'contents' permission set to 'write': .github/workflows/backport.yml:10","Info: topLevel 'contents' permission set to 'read': .github/workflows/bench.yml:7","Info: topLevel 'contents' permission set to 'read': .github/workflows/codeql.yml:24","Info: topLevel 'contents' permission set to 'read': .github/workflows/nightly.yml:9","Info: topLevel 'contents' permission set to 'read': .github/workflows/nodejs-shared.yml:13","Info: topLevel 'contents' permission set to 'read': .github/workflows/nodejs.yml:13","Info: topLevel 'contents' permission set to 'read': .github/workflows/release-create-pr.yml:4","Info: topLevel 'contents' permission set to 'read': .github/workflows/release.yml:11","Info: topLevel permissions set to 'read-all': .github/workflows/scorecard.yml:18","Info: topLevel 'contents' permission set to 'read': .github/workflows/test.yml:14","Info: topLevel 'contents' permission set to 'read': .github/workflows/triggered-autobahn.yml:9","Warn: topLevel 'contents' permission set to 'write': .github/workflows/update-cache-tests.yml:9","Warn: topLevel 'contents' permission set to 'write': .github/workflows/update-wpt.yml:9"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#token-permissions"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":8,"reason":"binaries present in source code","details":["Warn: binary detected: lib/llhttp/llhttp.wasm:1","Warn: binary detected: lib/llhttp/llhttp_simd.wasm:1"],"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":3,"reason":"dependency not pinned by hash detected -- score normalized to 3","details":["Warn: third-party GitHubAction not pinned by hash: .github/workflows/autobahn.yml:41: update your workflow using https://app.stepsecurity.io/secureworkflow/nodejs/undici/autobahn.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/backport.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/nodejs/undici/backport.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-create-pr.yml:33: update your workflow using https://app.stepsecurity.io/secureworkflow/nodejs/undici/release-create-pr.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-create-pr.yml:34: update your workflow using https://app.stepsecurity.io/secureworkflow/nodejs/undici/release-create-pr.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-create-pr.yml:52: update your workflow using https://app.stepsecurity.io/secureworkflow/nodejs/undici/release-create-pr.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/nodejs/undici/release.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/nodejs/undici/release.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:52: update your workflow using https://app.stepsecurity.io/secureworkflow/nodejs/undici/release.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:53: update your workflow using https://app.stepsecurity.io/secureworkflow/nodejs/undici/release.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:69: update your workflow using https://app.stepsecurity.io/secureworkflow/nodejs/undici/release.yml/main?enable=pin","Warn: npmCommand not pinned by hash: test/fixtures/wpt/resources/webidl2/build.sh:7","Warn: npmCommand not pinned by hash: .github/workflows/bench.yml:25","Warn: npmCommand not pinned by hash: .github/workflows/bench.yml:27","Warn: npmCommand not pinned by hash: .github/workflows/bench.yml:46","Warn: npmCommand not pinned by hash: .github/workflows/bench.yml:48","Warn: npmCommand not pinned by hash: .github/workflows/bench.yml:68","Warn: npmCommand not pinned by hash: .github/workflows/bench.yml:70","Warn: npmCommand not pinned by hash: .github/workflows/bench.yml:89","Warn: npmCommand not pinned by hash: .github/workflows/bench.yml:91","Warn: npmCommand not pinned by hash: .github/workflows/bench.yml:111","Warn: npmCommand not pinned by hash: .github/workflows/bench.yml:113","Warn: npmCommand not pinned by hash: .github/workflows/bench.yml:132","Warn: npmCommand not pinned by hash: .github/workflows/bench.yml:134","Warn: npmCommand not pinned by hash: .github/workflows/nodejs-shared.yml:42","Warn: npmCommand not pinned by hash: .github/workflows/nodejs.yml:49","Warn: npmCommand not pinned by hash: .github/workflows/nodejs.yml:98","Warn: npmCommand not pinned by hash: .github/workflows/nodejs.yml:162","Warn: npmCommand not pinned by hash: .github/workflows/nodejs.yml:183","Warn: npmCommand not pinned by hash: .github/workflows/nodejs.yml:204","Warn: npmCommand not pinned by hash: .github/workflows/release.yml:58","Warn: npmCommand not pinned by hash: .github/workflows/release.yml:59","Warn: npmCommand not pinned by hash: .github/workflows/test.yml:41","Info:  42 out of  50 GitHub-owned GitHubAction dependencies pinned","Info:   9 out of  11 third-party GitHubAction dependencies pinned","Info:   0 out of  22 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#cii-best-practices"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":9,"reason":"SAST tool detected but not run on all commits","details":["Info: SAST configuration detected: CodeQL","Warn: 28 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#sast"}},{"name":"Fuzzing","score":10,"reason":"project is fuzzed","details":["Info: JavaScriptPropertyBasedTesting integration found: test/fuzzing/fuzzing.test.js:4"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#fuzzing"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/release.yml:40"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#packaging"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#branch-protection"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#license"}},{"name":"CI-Tests","score":10,"reason":"30 out of 30 merged PRs checked by a CI test -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project runs tests before pull requests are merged.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#ci-tests"}},{"name":"Contributors","score":10,"reason":"project has 77 contributing companies or organizations","details":["Info: found contributions from: CasparCG, ES-Community, EpicGames, GonzagaAccess, Level, LyraSearch, Pseudo-Corp, Puella-Care, Somerset-SIDeR-Programme, TrainingPlay, Trendyol, WebAssembly, WinterTC55, ada-url, adonisjs, auth0, aws, awslabs, busterjs, cheminfo, cheminfo-js, cloudflare, cloudflare-whatwg, cowtech, danger, dymonaz, elastic, expressjs, fastify, flarelabs-net, freeCodeCamp, fvgdev, h3js, h5o, hackwitus, harperdb, image-js, insidewarehouse, jshttp, lexplano, malijs, mbi health, minibuf, mljs, mochajs, mqttjs, nearform, nock, nodejs, nodejs-private, nodesource, nxtedition, oauth-wg, okta, openid, openjs-foundation, ossf, passionfruit-earth, pillarjs, pinojs, piscinajs, pkgjs, platformatic, pnpm, pouchdb, puella care, relevantfruit, sagemath, simdutf, trendyol, tu wien, upringjs, w3c, wasm-signatures, web-platform-tests, zakodium, zakodium-oss"],"documentation":{"short":"Determines if the project has a set of contributors from multiple organizations (e.g., companies).","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#contributors"}}]},"last_synced_at":"2025-08-21T08:18:20.034Z","repository_id":36969980,"created_at":"2025-08-21T08:18:20.034Z","updated_at":"2025-08-21T08:18:20.034Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290977,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","http","nodejs"],"created_at":"2024-07-30T19:01:16.033Z","updated_at":"2026-04-01T18:55:26.825Z","avatar_url":"https://github.com/nodejs.png","language":"JavaScript","readme":"# undici\n\n[![Node CI](https://github.com/nodejs/undici/actions/workflows/ci.yml/badge.svg)](https://github.com/nodejs/undici/actions/workflows/nodejs.yml) [![neostandard javascript style](https://img.shields.io/badge/neo-standard-7fffff?style=flat\\\u0026labelColor=ff80ff)](https://github.com/neostandard/neostandard) [![npm version](https://badge.fury.io/js/undici.svg)](https://badge.fury.io/js/undici) [![codecov](https://codecov.io/gh/nodejs/undici/branch/main/graph/badge.svg?token=yZL6LtXkOA)](https://codecov.io/gh/nodejs/undici)\n\nAn HTTP/1.1 client, written from scratch for Node.js.\n\n\u003e Undici means eleven in Italian. 1.1 -\u003e 11 -\u003e Eleven -\u003e Undici.\nIt is also a Stranger Things reference.\n\n## How to get involved\n\nHave a question about using Undici? Open a [Q\u0026A Discussion](https://github.com/nodejs/undici/discussions/new) or join our official OpenJS [Slack](https://openjs-foundation.slack.com/archives/C01QF9Q31QD) channel.\n\nLooking to contribute? Start by reading the [contributing guide](./CONTRIBUTING.md)\n\n## Install\n\n```\nnpm i undici\n```\n\n## Benchmarks\n\nThe benchmark is a simple getting data [example](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark.js) using a\n50 TCP connections with a pipelining depth of 10 running on Node 22.11.0.\n\n```\n┌────────────────────────┬─────────┬────────────────────┬────────────┬─────────────────────────┐\n│  Tests                 │ Samples │ Result             │ Tolerance  │ Difference with slowest │\n├────────────────────────┼─────────┼────────────────────┼────────────┼─────────────────────────┤\n│  'axios'               │ 15      │ '5708.26 req/sec'  │ '± 2.91 %' │ '-'                     │\n│  'http - no keepalive' │ 10      │ '5809.80 req/sec'  │ '± 2.30 %' │ '+ 1.78 %'              │\n│  'request'             │ 30      │ '5828.80 req/sec'  │ '± 2.91 %' │ '+ 2.11 %'              │\n│  'undici - fetch'      │ 40      │ '5903.78 req/sec'  │ '± 2.87 %' │ '+ 3.43 %'              │\n│  'node-fetch'          │ 10      │ '5945.40 req/sec'  │ '± 2.13 %' │ '+ 4.15 %'              │\n│  'got'                 │ 35      │ '6511.45 req/sec'  │ '± 2.84 %' │ '+ 14.07 %'             │\n│  'http - keepalive'    │ 65      │ '9193.24 req/sec'  │ '± 2.92 %' │ '+ 61.05 %'             │\n│  'superagent'          │ 35      │ '9339.43 req/sec'  │ '± 2.95 %' │ '+ 63.61 %'             │\n│  'undici - pipeline'   │ 50      │ '13364.62 req/sec' │ '± 2.93 %' │ '+ 134.13 %'            │\n│  'undici - stream'     │ 95      │ '18245.36 req/sec' │ '± 2.99 %' │ '+ 219.63 %'            │\n│  'undici - request'    │ 50      │ '18340.17 req/sec' │ '± 2.84 %' │ '+ 221.29 %'            │\n│  'undici - dispatch'   │ 40      │ '22234.42 req/sec' │ '± 2.94 %' │ '+ 289.51 %'            │\n└────────────────────────┴─────────┴────────────────────┴────────────┴─────────────────────────┘\n```\n\n## Undici vs. Fetch\n\n### Overview\n\nNode.js includes a built-in `fetch()` implementation powered by undici starting from Node.js v18. However, there are important differences between using the built-in fetch and installing undici as a separate module.\n\n### Built-in Fetch (Node.js v18+)\n\nNode.js's built-in fetch is powered by a bundled version of undici:\n\n```js\n// Available globally in Node.js v18+\nconst response = await fetch('https://api.example.com/data');\nconst data = await response.json();\n\n// Check the bundled undici version\nconsole.log(process.versions.undici); // e.g., \"5.28.4\"\n```\n\n**Pros:**\n- No additional dependencies required\n- Works across different JavaScript runtimes\n- Automatic compression handling (gzip, deflate, br)\n- Built-in caching support (in development)\n\n**Cons:**\n- Limited to the undici version bundled with your Node.js version\n- Less control over connection pooling and advanced features\n- Error handling follows Web API standards (errors wrapped in `TypeError`)\n- Performance overhead due to Web Streams implementation\n\n### Undici Module\n\nInstalling undici as a separate module gives you access to the latest features and APIs:\n\n```bash\nnpm install undici\n```\n\n```js\nimport { request, fetch, Agent, setGlobalDispatcher } from 'undici';\n\n// Use undici.request for maximum performance\nconst { statusCode, headers, body } = await request('https://api.example.com/data');\nconst data = await body.json();\n\n// Or use undici.fetch with custom configuration\nconst agent = new Agent({ keepAliveTimeout: 10000 });\nsetGlobalDispatcher(agent);\nconst response = await fetch('https://api.example.com/data');\n```\n\n**Pros:**\n- Latest undici features and bug fixes\n- Access to advanced APIs (`request`, `stream`, `pipeline`)\n- Fine-grained control over connection pooling\n- Better error handling with clearer error messages\n- Superior performance, especially with `undici.request`\n- HTTP/1.1 pipelining support\n- Custom interceptors and middleware\n- Advanced features like `ProxyAgent`, `Socks5Agent`, `MockAgent`\n\n**Cons:**\n- Additional dependency to manage\n- Larger bundle size\n\n### When to Use Each\n\n#### Use Built-in Fetch When:\n- You want zero dependencies\n- Building isomorphic code that runs in browsers and Node.js\n- Publishing to npm and want to maximize compatibility with JS runtimes\n- Simple HTTP requests without advanced configuration\n- You're publishing to npm and you want to maximize compatiblity\n- You don't depend on features from a specific version of undici\n\n#### Use Undici Module When:\n- You need the latest undici features and performance improvements\n- You require advanced connection pooling configuration\n- You need APIs not available in the built-in fetch (`ProxyAgent`, `Socks5Agent`, `MockAgent`, etc.)\n- Performance is critical (use `undici.request` for maximum speed)\n- You want better error handling and debugging capabilities\n- You need HTTP/1.1 pipelining or advanced interceptors\n- You prefer decoupled protocol and API interfaces\n\n### Performance Comparison\n\nBased on benchmarks, here's the typical performance hierarchy:\n\n1. **`undici.request()`** - Fastest, most efficient\n2. **`undici.fetch()`** - Good performance, standard compliance\n3. **Node.js `http`/`https`** - Baseline performance\n\n### Migration Guide\n\nIf you're currently using built-in fetch and want to migrate to undici:\n\n```js\n// Before: Built-in fetch\nconst response = await fetch('https://api.example.com/data');\n\n// After: Undici fetch (drop-in replacement)\nimport { fetch } from 'undici';\nconst response = await fetch('https://api.example.com/data');\n\n// Or: Undici request (better performance)\nimport { request } from 'undici';\nconst { statusCode, body } = await request('https://api.example.com/data');\nconst data = await body.json();\n```\n\n### Keep `fetch` and `FormData` together\n\nWhen you send a `FormData` body, keep `fetch` and `FormData` from the same\nimplementation.\n\nUse one of these patterns:\n\n```js\n// Built-in globals\nconst body = new FormData()\nbody.set('name', 'some')\nawait fetch('https://example.com', {\n  method: 'POST',\n  body\n})\n```\n\n```js\n// undici module imports\nimport { fetch, FormData } from 'undici'\n\nconst body = new FormData()\nbody.set('name', 'some')\nawait fetch('https://example.com', {\n  method: 'POST',\n  body\n})\n```\n\nIf you want the installed `undici` package to provide the globals, call\n`install()` first:\n\n```js\nimport { install } from 'undici'\n\ninstall()\n\nconst body = new FormData()\nbody.set('name', 'some')\nawait fetch('https://example.com', {\n  method: 'POST',\n  body\n})\n```\n\n`install()` replaces the global `fetch`, `Headers`, `Response`, `Request`, and\n`FormData` implementations with undici's versions, so they all match.\n\nAvoid mixing a global `FormData` with `undici.fetch()`, or `undici.FormData`\nwith the built-in global `fetch()`.\n\n### Version Compatibility\n\nYou can check which version of undici is bundled with your Node.js version:\n\n```js\nconsole.log(process.versions.undici);\n```\n\nInstalling undici as a module allows you to use a newer version than what's bundled with Node.js, giving you access to the latest features and performance improvements.\n\n## Quick Start\n\n### Basic Request\n\n```js\nimport { request } from 'undici'\n\nconst {\n  statusCode,\n  headers,\n  trailers,\n  body\n} = await request('http://localhost:3000/foo')\n\nconsole.log('response received', statusCode)\nconsole.log('headers', headers)\n\nfor await (const data of body) { console.log('data', data) }\n\nconsole.log('trailers', trailers)\n```\n\n### Using Cache Interceptor\n\nUndici provides a powerful HTTP caching interceptor that follows HTTP caching best practices. Here's how to use it:\n\n```js\nimport { fetch, Agent, interceptors, cacheStores } from 'undici';\n\n// Create a client with cache interceptor\nconst client = new Agent().compose(interceptors.cache({\n  // Optional: Configure cache store (defaults to MemoryCacheStore)\n  store: new cacheStores.MemoryCacheStore({\n    maxSize: 100 * 1024 * 1024, // 100MB\n    maxCount: 1000,\n    maxEntrySize: 5 * 1024 * 1024 // 5MB\n  }),\n  \n  // Optional: Specify which HTTP methods to cache (default: ['GET', 'HEAD'])\n  methods: ['GET', 'HEAD']\n}));\n\n// Set the global dispatcher to use our caching client\nsetGlobalDispatcher(client);\n\n// Now all fetch requests will use the cache\nasync function getData() {\n  const response = await fetch('https://api.example.com/data');\n  // The server should set appropriate Cache-Control headers in the response\n  // which the cache will respect based on the cache policy\n  return response.json();\n}\n\n// First request - fetches from origin\nconst data1 = await getData();\n\n// Second request - served from cache if within max-age\nconst data2 = await getData();\n```\n\n#### Key Features:\n- **Automatic Caching**: Respects `Cache-Control` and `Expires` headers\n- **Validation**: Supports `ETag` and `Last-Modified` validation\n- **Storage Options**: In-memory or persistent SQLite storage\n- **Flexible**: Configure cache size, TTL, and more\n\n## Global Installation\n\nUndici provides an `install()` function to add all WHATWG fetch classes to `globalThis`, making them available globally:\n\n```js\nimport { install } from 'undici'\n\n// Install all WHATWG fetch classes globally\ninstall()\n\n// Now you can use fetch classes globally without importing\nconst response = await fetch('https://api.example.com/data')\nconst data = await response.json()\n\n// All classes are available globally:\nconst headers = new Headers([['content-type', 'application/json']])\nconst request = new Request('https://example.com')\nconst formData = new FormData()\nconst ws = new WebSocket('wss://example.com')\nconst eventSource = new EventSource('https://example.com/events')\n```\n\nThe `install()` function adds the following classes to `globalThis`:\n\n- `fetch` - The fetch function\n- `Headers` - HTTP headers management\n- `Response` - HTTP response representation\n- `Request` - HTTP request representation\n- `FormData` - Form data handling\n- `WebSocket` - WebSocket client\n- `CloseEvent`, `ErrorEvent`, `MessageEvent` - WebSocket events\n- `EventSource` - Server-sent events client\n\nWhen you call `install()`, these globals come from the same undici\nimplementation. For example, global `fetch` and global `FormData` will both be\nundici's versions, which is the recommended setup if you want to use undici\nthrough globals.\n\nThis is useful for:\n- Polyfilling environments that don't have fetch\n- Ensuring consistent fetch behavior across different Node.js versions\n- Making undici's implementations available globally for libraries that expect them\n\n## Body Mixins\n\nThe `body` mixins are the most common way to format the request/response body. Mixins include:\n\n- [`.arrayBuffer()`](https://fetch.spec.whatwg.org/#dom-body-arraybuffer)\n- [`.blob()`](https://fetch.spec.whatwg.org/#dom-body-blob)\n- [`.bytes()`](https://fetch.spec.whatwg.org/#dom-body-bytes)\n- [`.json()`](https://fetch.spec.whatwg.org/#dom-body-json)\n- [`.text()`](https://fetch.spec.whatwg.org/#dom-body-text)\n\n\u003e [!NOTE]\n\u003e The body returned from `undici.request` does not implement `.formData()`.\n\nExample usage:\n\n```js\nimport { request } from 'undici'\n\nconst {\n  statusCode,\n  headers,\n  trailers,\n  body\n} = await request('http://localhost:3000/foo')\n\nconsole.log('response received', statusCode)\nconsole.log('headers', headers)\nconsole.log('data', await body.json())\nconsole.log('trailers', trailers)\n```\n\n_Note: Once a mixin has been called then the body cannot be reused, thus calling additional mixins on `.body`, e.g. `.body.json(); .body.text()` will result in an error `TypeError: unusable` being thrown and returned through the `Promise` rejection._\n\nShould you need to access the `body` in plain-text after using a mixin, the best practice is to use the `.text()` mixin first and then manually parse the text to the desired format.\n\nFor more information about their behavior, please reference the body mixin from the [Fetch Standard](https://fetch.spec.whatwg.org/#body-mixin).\n\n## Common API Methods\n\nThis section documents our most commonly used API methods. Additional APIs are documented in their own files within the [docs](./docs/) folder and are accessible via the navigation list on the left side of the docs site.\n\n### `undici.request([url, options]): Promise`\n\nArguments:\n\n* **url** `string | URL | UrlObject`\n* **options** [`RequestOptions`](./docs/docs/api/Dispatcher.md#parameter-requestoptions)\n  * **dispatcher** `Dispatcher` - Default: [getGlobalDispatcher](#undicigetglobaldispatcher)\n  * **method** `String` - Default: `PUT` if `options.body`, otherwise `GET`\n\nReturns a promise with the result of the `Dispatcher.request` method.\n\nCalls `options.dispatcher.request(options)`.\n\nSee [Dispatcher.request](./docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback) for more details, and [request examples](./docs/examples/README.md) for examples.\n\n### `undici.stream([url, options, ]factory): Promise`\n\nArguments:\n\n* **url** `string | URL | UrlObject`\n* **options** [`StreamOptions`](./docs/docs/api/Dispatcher.md#parameter-streamoptions)\n  * **dispatcher** `Dispatcher` - Default: [getGlobalDispatcher](#undicigetglobaldispatcher)\n  * **method** `String` - Default: `PUT` if `options.body`, otherwise `GET`\n* **factory** `Dispatcher.stream.factory`\n\nReturns a promise with the result of the `Dispatcher.stream` method.\n\nCalls `options.dispatcher.stream(options, factory)`.\n\nSee [Dispatcher.stream](./docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback) for more details.\n\n### `undici.pipeline([url, options, ]handler): Duplex`\n\nArguments:\n\n* **url** `string | URL | UrlObject`\n* **options** [`PipelineOptions`](./docs/docs/api/Dispatcher.md#parameter-pipelineoptions)\n  * **dispatcher** `Dispatcher` - Default: [getGlobalDispatcher](#undicigetglobaldispatcher)\n  * **method** `String` - Default: `PUT` if `options.body`, otherwise `GET`\n* **handler** `Dispatcher.pipeline.handler`\n\nReturns: `stream.Duplex`\n\nCalls `options.dispatch.pipeline(options, handler)`.\n\nSee [Dispatcher.pipeline](./docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler) for more details.\n\n### `undici.connect([url, options]): Promise`\n\nStarts two-way communications with the requested resource using [HTTP CONNECT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/CONNECT).\n\nArguments:\n\n* **url** `string | URL | UrlObject`\n* **options** [`ConnectOptions`](./docs/docs/api/Dispatcher.md#parameter-connectoptions)\n  * **dispatcher** `Dispatcher` - Default: [getGlobalDispatcher](#undicigetglobaldispatcher)\n* **callback** `(err: Error | null, data: ConnectData | null) =\u003e void` (optional)\n\nReturns a promise with the result of the `Dispatcher.connect` method.\n\nCalls `options.dispatch.connect(options)`.\n\nSee [Dispatcher.connect](./docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback) for more details.\n\n### `undici.fetch(input[, init]): Promise`\n\nImplements [fetch](https://fetch.spec.whatwg.org/#fetch-method).\n\n* https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch\n* https://fetch.spec.whatwg.org/#fetch-method\n\nBasic usage example:\n\n```js\nimport { fetch } from 'undici'\n\n\nconst res = await fetch('https://example.com')\nconst json = await res.json()\nconsole.log(json)\n```\n\nYou can pass an optional dispatcher to `fetch` as:\n\n```js\nimport { fetch, Agent } from 'undici'\n\nconst res = await fetch('https://example.com', {\n  // Mocks are also supported\n  dispatcher: new Agent({\n    keepAliveTimeout: 10,\n    keepAliveMaxTimeout: 10\n  })\n})\nconst json = await res.json()\nconsole.log(json)\n```\n\n#### `request.body`\n\nA body can be of the following types:\n\n- ArrayBuffer\n- ArrayBufferView\n- AsyncIterables\n- Blob\n- Iterables\n- String\n- URLSearchParams\n- FormData\n\nIn this implementation of fetch, ```request.body``` now accepts ```Async Iterables```. It is not present in the [Fetch Standard](https://fetch.spec.whatwg.org).\n\n```js\nimport { fetch } from 'undici'\n\nconst data = {\n  async *[Symbol.asyncIterator]() {\n    yield 'hello'\n    yield 'world'\n  },\n}\n\nawait fetch('https://example.com', { body: data, method: 'POST', duplex: 'half' })\n```\n\n[FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) besides text data and buffers can also utilize streams via [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) objects:\n\n```js\nimport { openAsBlob } from 'node:fs'\n\nconst file = await openAsBlob('./big.csv')\nconst body = new FormData()\nbody.set('file', file, 'big.csv')\n\nawait fetch('http://example.com', { method: 'POST', body })\n```\n\n#### `request.duplex`\n\n- `'half'`\n\nIn this implementation of fetch, `request.duplex` must be set if `request.body` is `ReadableStream` or `Async Iterables`, however, even though the value must be set to `'half'`, it is actually a _full_ duplex. For more detail refer to the [Fetch Standard](https://fetch.spec.whatwg.org/#dom-requestinit-duplex).\n\n#### `response.body`\n\nNodejs has two kinds of streams: [web streams](https://nodejs.org/api/webstreams.html), which follow the API of the WHATWG web standard found in browsers, and an older Node-specific [streams API](https://nodejs.org/api/stream.html). `response.body` returns a readable web stream. If you would prefer to work with a Node stream you can convert a web stream using `.fromWeb()`.\n\n```js\nimport { fetch } from 'undici'\nimport { Readable } from 'node:stream'\n\nconst response = await fetch('https://example.com')\nconst readableWebStream = response.body\nconst readableNodeStream = Readable.fromWeb(readableWebStream)\n```\n\n## Specification Compliance\n\nThis section documents parts of the [HTTP/1.1](https://www.rfc-editor.org/rfc/rfc9110.html) and [Fetch Standard](https://fetch.spec.whatwg.org) that Undici does\nnot support or does not fully implement.\n\n#### CORS\n\nUnlike browsers, Undici does not implement CORS (Cross-Origin Resource Sharing) checks by default. This means:\n\n- No preflight requests are automatically sent for cross-origin requests\n- No validation of `Access-Control-Allow-Origin` headers is performed\n- Requests to any origin are allowed regardless of the source\n\nThis behavior is intentional for server-side environments where CORS restrictions are typically unnecessary. If your application requires CORS-like protections, you will need to implement these checks manually.\n\n#### Garbage Collection\n\n* https://fetch.spec.whatwg.org/#garbage-collection\n\nThe [Fetch Standard](https://fetch.spec.whatwg.org) allows users to skip consuming the response body by relying on\n[garbage collection](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Memory_Management#garbage_collection) to release connection resources.\n\nGarbage collection in Node is less aggressive and deterministic\n(due to the lack of clear idle periods that browsers have through the rendering refresh rate)\nwhich means that leaving the release of connection resources to the garbage collector can lead\nto excessive connection usage, reduced performance (due to less connection re-use), and even\nstalls or deadlocks when running out of connections.\nTherefore, __it is important to always either consume or cancel the response body anyway__.\n\n```js\n// Do\nconst { body, headers } = await fetch(url);\nfor await (const chunk of body) {\n  // force consumption of body\n}\n\n// Do not\nconst { headers } = await fetch(url);\n```\n\nHowever, if you want to get only headers, it might be better to use `HEAD` request method. Usage of this method will obviate the need for consumption or cancelling of the response body. See [MDN - HTTP - HTTP request methods - HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) for more details.\n\n```js\nconst headers = await fetch(url, { method: 'HEAD' })\n  .then(res =\u003e res.headers)\n```\n\nNote that consuming the response body is _mandatory_ for `request`:\n\n```js\n// Do\nconst { body, headers } = await request(url);\nawait body.dump(); // force consumption of body\n\n// Do not\nconst { headers } = await request(url);\n```\n\n#### Forbidden and Safelisted Header Names\n\n* https://fetch.spec.whatwg.org/#cors-safelisted-response-header-name\n* https://fetch.spec.whatwg.org/#forbidden-header-name\n* https://fetch.spec.whatwg.org/#forbidden-response-header-name\n* https://github.com/wintercg/fetch/issues/6\n\nThe [Fetch Standard](https://fetch.spec.whatwg.org) requires implementations to exclude certain headers from requests and responses. In browser environments, some headers are forbidden so the user agent remains in full control over them. In Undici, these constraints are removed to give more control to the user.\n\n#### Content-Encoding\n\n* https://www.rfc-editor.org/rfc/rfc9110#field.content-encoding\n\nUndici limits the number of `Content-Encoding` layers in a response to **5** to prevent resource exhaustion attacks. If a server responds with more than 5 content-encodings (e.g., `Content-Encoding: gzip, gzip, gzip, gzip, gzip, gzip`), the fetch will be rejected with an error. This limit matches the approach taken by [curl](https://curl.se/docs/CVE-2022-32206.html) and [urllib3](https://github.com/advisories/GHSA-gm62-xv2j-4rw9).\n\n#### `undici.upgrade([url, options]): Promise`\n\nUpgrade to a different protocol. See [MDN - HTTP - Protocol upgrade mechanism](https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism) for more details.\n\nArguments:\n\n* **url** `string | URL | UrlObject`\n* **options** [`UpgradeOptions`](./docs/docs/api/Dispatcher.md#parameter-upgradeoptions)\n  * **dispatcher** `Dispatcher` - Default: [getGlobalDispatcher](#undicigetglobaldispatcher)\n* **callback** `(error: Error | null, data: UpgradeData) =\u003e void` (optional)\n\nReturns a promise with the result of the `Dispatcher.upgrade` method.\n\nCalls `options.dispatcher.upgrade(options)`.\n\nSee [Dispatcher.upgrade](./docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback) for more details.\n\n### `undici.setGlobalDispatcher(dispatcher)`\n\n* dispatcher `Dispatcher`\n\nSets the global dispatcher used by Common API Methods. Global dispatcher is shared among compatible undici modules,\nincluding undici that is bundled internally with node.js.\n\n### `undici.getGlobalDispatcher()`\n\nGets the global dispatcher used by Common API Methods.\n\nReturns: `Dispatcher`\n\n### `undici.setGlobalOrigin(origin)`\n\n* origin `string | URL | undefined`\n\nSets the global origin used in `fetch`.\n\nIf `undefined` is passed, the global origin will be reset. This will cause `Response.redirect`, `new Request()`, and `fetch` to throw an error when a relative path is passed.\n\n```js\nsetGlobalOrigin('http://localhost:3000')\n\nconst response = await fetch('/api/ping')\n\nconsole.log(response.url) // http://localhost:3000/api/ping\n```\n\n### `undici.getGlobalOrigin()`\n\nGets the global origin used in `fetch`.\n\nReturns: `URL`\n\n### `UrlObject`\n\n* **port** `string | number` (optional)\n* **path** `string` (optional)\n* **pathname** `string` (optional)\n* **hostname** `string` (optional)\n* **origin** `string` (optional)\n* **protocol** `string` (optional)\n* **search** `string` (optional)\n\n#### Expect\n\nUndici does not support the `Expect` request header field. The request\nbody is  always immediately sent and the `100 Continue` response will be\nignored.\n\nRefs: https://tools.ietf.org/html/rfc7231#section-5.1.1\n\n#### Pipelining\n\nUndici will only use pipelining if configured with a `pipelining` factor\ngreater than `1`. Also it is important to pass `blocking: false` to the\nrequest options to properly pipeline requests.\n\nUndici always assumes that connections are persistent and will immediately\npipeline requests, without checking whether the connection is persistent.\nHence, automatic fallback to HTTP/1.0 or HTTP/1.1 without pipelining is\nnot supported.\n\nUndici will immediately pipeline when retrying requests after a failed\nconnection. However, Undici will not retry the first remaining requests in\nthe prior pipeline and instead error the corresponding callback/promise/stream.\n\nUndici will abort all running requests in the pipeline when any of them are\naborted.\n\n* Refs: https://tools.ietf.org/html/rfc2616#section-8.1.2.2\n* Refs: https://tools.ietf.org/html/rfc7230#section-6.3.2\n\n#### Manual Redirect\n\nSince it is not possible to manually follow an HTTP redirect on the server-side,\nUndici returns the actual response instead of an `opaqueredirect` filtered one\nwhen invoked with a `manual` redirect. This aligns `fetch()` with the other\nimplementations in Deno and Cloudflare Workers.\n\nRefs: https://fetch.spec.whatwg.org/#atomic-http-redirect-handling\n\n### Workarounds\n\n#### Network address family autoselection.\n\nIf you experience problem when connecting to a remote server that is resolved by your DNS servers to a IPv6 (AAAA record)\nfirst, there are chances that your local router or ISP might have problem connecting to IPv6 networks. In that case\nundici will throw an error with code `UND_ERR_CONNECT_TIMEOUT`.\n\nIf the target server resolves to both a IPv6 and IPv4 (A records) address and you are using a compatible Node version\n(18.3.0 and above), you can fix the problem by providing the `autoSelectFamily` option (support by both `undici.request`\nand `undici.Agent`) which will enable the family autoselection algorithm when establishing the connection.\n\n## Collaborators\n\n* [__Daniele Belardi__](https://github.com/dnlup), \u003chttps://www.npmjs.com/~dnlup\u003e\n* [__Ethan Arrowood__](https://github.com/ethan-arrowood), \u003chttps://www.npmjs.com/~ethan_arrowood\u003e\n* [__Matteo Collina__](https://github.com/mcollina), \u003chttps://www.npmjs.com/~matteo.collina\u003e\n* [__Matthew Aitken__](https://github.com/KhafraDev), \u003chttps://www.npmjs.com/~khaf\u003e\n* [__Robert Nagy__](https://github.com/ronag), \u003chttps://www.npmjs.com/~ronag\u003e\n* [__Szymon Marczak__](https://github.com/szmarczak), \u003chttps://www.npmjs.com/~szmarczak\u003e\n\n## Past Collaborators\n* [__Tomas Della Vedova__](https://github.com/delvedor), \u003chttps://www.npmjs.com/~delvedor\u003e\n\n### Releasers\n\n* [__Ethan Arrowood__](https://github.com/ethan-arrowood), \u003chttps://www.npmjs.com/~ethan_arrowood\u003e\n* [__Matteo Collina__](https://github.com/mcollina), \u003chttps://www.npmjs.com/~matteo.collina\u003e\n* [__Robert Nagy__](https://github.com/ronag), \u003chttps://www.npmjs.com/~ronag\u003e\n* [__Matthew Aitken__](https://github.com/KhafraDev), \u003chttps://www.npmjs.com/~khaf\u003e\n\n## Long Term Support\n\nUndici aligns with the Node.js LTS schedule. The following table shows the supported versions:\n\n| Undici Version | Bundled in Node.js | Node.js Versions Supported | End of Life |\n|----------------|-------------------|----------------------------|-------------|\n| 5.x           | 18.x              | ≥14.0 (tested: 14, 16, 18) | 2024-04-30  |\n| 6.x           | 20.x, 22.x       | ≥18.17 (tested: 18, 20, 21, 22) | 2026-04-30  |\n| 7.x           | 24.x              | ≥20.18.1 (tested: 20, 22, 24) | 2027-04-30  |\n\n## License\n\nMIT\n","funding_links":["https://github.com/sponsors/nodejs","https://opencollective.com/nodejs"],"categories":["JavaScript","Packages","Repository","nodejs","包","网络信息服务"],"sub_categories":["HTTP","网络协议"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodejs%2Fundici","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnodejs%2Fundici","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodejs%2Fundici/lists"}