npm Registry Fetch Client

19.1.1 · active · verified Tue Apr 21

npm-registry-fetch is a Node.js library providing a fetch-like API for interacting with npm registry APIs. It abstracts away complexities like selecting the correct registry, handling package scopes, and managing authentication details based on standard npm configuration. This package is the modern successor to npm-registry-client. Its current stable version is 19.1.1, and it maintains a consistent, active release cadence with frequent patch and minor updates, and occasional major version bumps primarily for Node.js engine compatibility or internal API refinements. A key differentiator is its deep integration with npm's ecosystem, ensuring correct behavior for features like cache revalidation for write operations, which makes it an authoritative choice for programmatic interaction with the npm registry.

Common errors

```
Error: `npm-registry-fetch` requires Node.js version `^20.17.0 || >=22.9.0`
```
cause The Node.js version installed is older than the minimum required by the `npm-registry-fetch` package.

fix Upgrade 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
```
cause 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.

fix Ensure `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
```
cause 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).

fix Refactor your import statements to use ES module syntax: `import npmFetch from 'npm-registry-fetch';`.

Warnings

breaking Version 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.
Fix: Upgrade your Node.js environment to a compatible version (e.g., Node.js 20.17.x or 22.9.x or newer).
breaking Version 18.0.0 of `npm-registry-fetch` dropped support for Node.js versions older than `18.17.0 || >=20.5.0`.
Fix: Upgrade your Node.js environment to a compatible version (e.g., Node.js 18.17.x or 20.5.x or newer).
breaking The 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.
Fix: Refactor code to no longer use `cleanUrl`. If similar functionality is required, implement custom URL cleaning logic or use a dedicated URL utility library.
gotcha Requests 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.
Fix: Be 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.

Install

npm install npm-registry-fetch npm
yarn add npm-registry-fetch yarn
pnpm add npm-registry-fetch pnpm

Imports

fetch
wrong:
```
import { fetch } from 'npm-registry-fetch';
```
correct:
```
import npmFetch 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
wrong:
```
import { json } from 'npm-registry-fetch';
```
correct:
```
import npmFetch from 'npm-registry-fetch'; await npmFetch.json('/-/ping');
```
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
wrong:
```
import { jsonStream } from 'npm-registry-fetch';
```
correct:
```
import npmFetch from 'npm-registry-fetch'; npmFetch.json.stream('/-/all', 'rows.*.doc');
```
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.

Quickstart

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();

view raw JSON →