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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fetch
✓ import npmFetch from 'npm-registry-fetch';
✗ import { fetch } from 'npm-registry-fetch';
The main export is a default function, commonly aliased to `npmFetch` or `fetch`. It's callable directly to make requests and also has properties like `json` and `json.stream` for convenience.
fetch.json
✓ import npmFetch from 'npm-registry-fetch'; await npmFetch.json('/-/ping');
✗ import { json } from 'npm-registry-fetch';
This utility method is accessed as a property of the default exported `fetch` function and directly parses the response body as JSON.
fetch.json.stream
✓ import npmFetch from 'npm-registry-fetch'; npmFetch.json.stream('/-/all', 'rows.*.doc');
✗ import { jsonStream } from 'npm-registry-fetch';
This method provides streaming JSON parsing, emitting individual entries through a stream, and is nested under the `json` property of the default exported `fetch` function.
Demonstrates how to use `npm-registry-fetch` to make a basic GET request to the npm registry's ping endpoint, handling both raw `Response` objects and using the `fetch.json` utility for direct JSON parsing.
import npmFetch from 'npm-registry-fetch';
async function fetchPing() {
try {
// Basic fetch request to the npm registry ping endpoint
const res = await npmFetch('/-/ping', {
// Optional: Specify a custom registry, defaults to npmjs.org
// registry: 'https://registry.npmjs.org/',
// Optional: Pass an AbortSignal for request cancellation
// signal: AbortSignal.timeout(5000),
// Optional: Authentication token (e.g., from process.env)
// token: process.env.NPM_TOKEN ?? '',
});
console.log('Status:', res.status);
console.log('Headers:', res.headers.raw());
const data = await res.json(); // Standard Fetch API method to parse JSON body
console.log('Body (parsed JSON):', data);
} catch (error) {
console.error('Failed to fetch via raw response:', error.message);
}
try {
// Using the convenience method fetch.json for direct JSON parsing
const jsonBody = await npmFetch.json('/-/ping');
console.log('\nUsing npmFetch.json for ping:', jsonBody);
} catch (error) {
console.error('Failed to fetch via .json helper:', error.message);
}
}
fetchPing();
Debug
Known issues
breakingVersion 19.0.0 and later of `npm-registry-fetch` require Node.js version `^20.17.0 || >=22.9.0`. Older Node.js versions, including `18.x`, are no longer supported.fixUpgrade your Node.js environment to a compatible version (e.g., Node.js 20.17.x or 22.9.x or newer).
affects: >=19.0.0
breakingVersion 18.0.0 of `npm-registry-fetch` dropped support for Node.js versions older than `18.17.0 || >=20.5.0`.fixUpgrade your Node.js environment to a compatible version (e.g., Node.js 18.17.x or 20.5.x or newer).
affects: >=18.0.0 <19.0.0
breakingThe undocumented `cleanUrl` export was removed in version 17.0.0. If you were relying on this internal utility, you will need to find an alternative.fixRefactor code to no longer use `cleanUrl`. If similar functionality is required, implement custom URL cleaning logic or use a dedicated URL utility library.
affects: >=17.0.0
gotchaRequests containing `?write=true` in the query string will forcibly set `prefer-online: true`, `prefer-offline: false`, and `offline: false`. This ensures local caches are revalidated before a write operation, which might result in additional network requests even when `offline` mode is seemingly enabled.fixBe aware of this automatic cache revalidation for write operations. If you require strict offline behavior, ensure no `?write=true` parameter is present in your registry request URLs.
affects: >=1.0.0
Errors
Common errors & fixes
Error: `npm-registry-fetch` requires Node.js version `^20.17.0 || >=22.9.0`
The Node.js version installed is older than the minimum required by the `npm-registry-fetch` package.
fixUpgrade your Node.js environment to a compatible version (e.g., Node.js 20.17.x or 22.9.x or newer) using tools like `nvm` or your preferred Node.js version manager.
TypeError: npm_registry_fetch_1.default is not a function
This error typically occurs when using TypeScript or ES modules and trying to import a default export incorrectly, or misusing CommonJS `require` with ES module patterns.
fixEnsure `npm-registry-fetch` is imported as a default export using `import npmFetch from 'npm-registry-fetch';` for ESM, or `const npmFetch = require('npm-registry-fetch');` for CommonJS. Do not attempt to destructure it as a named export. ReferenceError: require is not defined in ES module scope
Attempting to use the CommonJS `require()` function within an ECMAScript module context (e.g., in a `.mjs` file or a file within a `type: "module"` package).
fixRefactor your import statements to use ES module syntax: `import npmFetch from 'npm-registry-fetch';`.
Audit
Dependencies
make-fetch-happenrequiredUnderlying HTTP client providing caching, retries, and network robustness.
minipass-fetchrequiredCore fetch implementation used internally for stream handling.
@npmcli/redactrequiredUsed for redacting sensitive information from logs and output.