Registry / http-networking / make-fetch-happen

make-fetch-happen

JSON →
library15.0.5jsnpmunverified

make-fetch-happen is an opinionated, robust Node.js HTTP client that extends the standard `fetch` API with critical features for real-world applications. Currently stable at version 15.0.5, it maintains a fairly active release cadence, with minor/patch updates occurring every few months and major versions roughly annually, aligning with Node.js LTS updates. It distinguishes itself by wrapping `minipass-fetch` and augmenting it with capabilities like automatic HTTP-semantics-aware request retries, comprehensive HTTP caching (`Cache-Control`, `ETag`, `304`s, offline fallback), request pooling, transparent gzip/deflate, and support for proxies (HTTP, HTTPS, SOCKS). Additionally, it provides Subresource Integrity (SRI) verification and integrates Node.js Stream support, making it a highly reliable and performant choice for network operations within the Node.js ecosystem, particularly for tools like `npm` itself.

npm install make-fetch-happen
INSTALL
IMPORT
SIG · MAKE-FETCH-HAPPEN
M
make-fetch-happen
http-networkingjavascriptv15.0.5
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

fetch
import makeFetchHappen from 'make-fetch-happen'; const fetch = makeFetchHappen;
import { fetch } from 'make-fetch-happen';
The default export is the fetch function. For CJS, use `require('make-fetch-happen')`.
fetch.defaults
import makeFetchHappen from 'make-fetch-happen'; const fetchWithDefaults = makeFetchHappen.defaults({ /* options */ });
import { defaults } from 'make-fetch-happen';
`.defaults` is a method on the default exported fetch function, not a separate named export.
Response
import makeFetchHappen, { Response } from 'make-fetch-happen'; // Or globally available in Node.js >=18
import { Response } from 'node-fetch';
While `make-fetch-happen` wraps `minipass-fetch` (which provides `Response`), in recent Node.js versions, `Response` is globally available. If needed for type hinting or specific imports, `make-fetch-happen` re-exports it.

This quickstart demonstrates how to configure `make-fetch-happen` with a persistent cache path and perform both initial and conditional HTTP requests, showcasing its caching capabilities.

import makeFetchHappen from 'make-fetch-happen'; const fetch = makeFetchHappen.defaults({ cachePath: './my-app-cache' // path where cache will be written (and read) }); // First request: fetches from the web and caches the response fetch('https://registry.npmjs.org/make-fetch-happen') .then(res => res.json()) // download the body as JSON .then(body => { console.log(`Initial fetch: got ${body.name} from web.`); // Second request: forces a conditional request to validate cache return fetch('https://registry.npmjs.org/make-fetch-happen', { cache: 'no-cache' // instructs to revalidate with the origin }); }) .then(res => { console.log(`Conditional fetch status: ${res.status}`); // Expected 304 if cache valid return res.json().then(body => { console.log(`Conditional fetch: got ${body.name} from cache (status ${res.status}).`); }); }) .catch(error => console.error('An error occurred:', error));
Debug
Known issues
breakingVersion 15.0.0 updated the minimum Node.js engine requirement to `^20.17.0 || >=22.9.0`. Older Node.js versions are no longer supported.
fix
Upgrade your Node.js environment to version 20.17.0 or higher, or to 22.9.0 or higher. For continuous integration, update environment configurations.
affects: >=15.0.0
breakingVersion 14.0.0 updated the minimum Node.js engine requirement to `^18.17.0 || >=20.5.0`. Older Node.js versions are no longer supported.
fix
Upgrade your Node.js environment to version 18.17.0 or higher, or to 20.5.0 or higher. Verify compatibility with other dependencies before upgrading.
affects: >=14.0.0 <15.0.0
gotchaPrior to v14.0.3, `make-fetch-happen` could incorrectly ignore the `NODE_TLS_REJECT_UNAUTHORIZED` environment variable when the `strictSSL` option was not explicitly defined, potentially leading to insecure connections.
fix
Upgrade to `make-fetch-happen@14.0.3` or newer. Explicitly set `strictSSL: true` in options if you rely on the default secure behavior and want to ensure it's not overridden by `NODE_TLS_REJECT_UNAUTHORIZED=0`.
affects: <14.0.3
gotchaVersion 15.0.5 included a fix for URL logging of npm credentials. This implies that prior versions might have inadvertently logged sensitive credential information in URLs under certain conditions.
fix
Upgrade to `make-fetch-happen@15.0.5` or newer immediately. Review logs generated by previous versions for potential credential exposure.
affects: <15.0.5
gotchaBefore v14.0.2, there were issues where the request signal (for aborting requests) was incorrectly used within the agent, potentially leading to unexpected request termination or resource leaks.
fix
Upgrade to `make-fetch-happen@14.0.2` or newer to ensure correct handling of request signals with agents.
affects: <14.0.2
Errors
Common errors & fixes
Error: make-fetch-happen requires Node.js version X or higher.
The installed Node.js version does not meet the minimum engine requirement specified by make-fetch-happen.
fix
Upgrade your Node.js environment to the version specified in the error message or the package's `engines` field (e.g., `nvm install 20` and `nvm use 20`).
SRI Mismatch
The Subresource Integrity (SRI) hash provided in the fetch options does not match the hash of the downloaded resource, indicating potential tampering or an incorrect hash.
fix
Verify the integrity hash (`opts.integrity`) against the actual resource's hash. If the resource has changed, generate a new SRI hash. If fetching a known resource, ensure the integrity hash is correct.
TypeError: makeFetchHappen.defaults is not a function
Attempting to call `.defaults` on `makeFetchHappen` when it's not imported correctly, or `makeFetchHappen` itself is undefined due to an incorrect import.
fix
Ensure you are importing the default export: `import makeFetchHappen from 'make-fetch-happen';` for ESM or `const makeFetchHappen = require('make-fetch-happen');` for CommonJS.
Proxy error: connect ECONNREFUSED
make-fetch-happen failed to establish a connection through the configured proxy server, often due to an incorrect proxy address, port, or an unresponsive proxy.
fix
Double-check your `opts.proxy` configuration, including the protocol (http, https, socks) and credentials. Ensure the proxy server is running and accessible from your environment.
EACCES: permission denied, open '/path/to/my-app-cache/content-v2/sha512-...' (or similar cache path error)
The application lacks sufficient write permissions for the specified `opts.cachePath` directory, preventing caching operations.
fix
Ensure the user running the Node.js process has read/write permissions to the `cachePath` directory. Consider changing the `cachePath` to a user-specific temporary directory or a location with appropriate permissions.
Upgrade
Version history
15.0.5latest on npm
Audit
Dependencies
minipass-fetchrequiredProvides the core fetch API implementation.
cacacherequiredUsed for robust HTTP caching on disk.
@npmcli/agentrequiredManages connection pooling, proxies, and DNS caching.
ssrirequiredProvides Subresource Integrity (SRI) verification.
@gar/promise-retryrequiredManages automatic request retries.
Agent activity
3 hits · last 30 days
node
2
Amazon
1
Resources