{"id":15732,"library":"npm-registry-fetch","title":"npm Registry Fetch Client","description":"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.","status":"active","version":"19.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/npm/npm-registry-fetch","tags":["javascript","npm","registry","fetch"],"install":[{"cmd":"npm install npm-registry-fetch","lang":"bash","label":"npm"},{"cmd":"yarn add npm-registry-fetch","lang":"bash","label":"yarn"},{"cmd":"pnpm add npm-registry-fetch","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Underlying HTTP client providing caching, retries, and network robustness.","package":"make-fetch-happen","optional":false},{"reason":"Core fetch implementation used internally for stream handling.","package":"minipass-fetch","optional":false},{"reason":"Used for redacting sensitive information from logs and output.","package":"@npmcli/redact","optional":false}],"imports":[{"note":"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.","wrong":"import { fetch } from 'npm-registry-fetch';","symbol":"fetch","correct":"import npmFetch from 'npm-registry-fetch';"},{"note":"This utility method is accessed as a property of the default exported `fetch` function and directly parses the response body as JSON.","wrong":"import { json } from 'npm-registry-fetch';","symbol":"fetch.json","correct":"import npmFetch from 'npm-registry-fetch'; await npmFetch.json('/-/ping');"},{"note":"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.","wrong":"import { jsonStream } from 'npm-registry-fetch';","symbol":"fetch.json.stream","correct":"import npmFetch from 'npm-registry-fetch'; npmFetch.json.stream('/-/all', 'rows.*.doc');"}],"quickstart":{"code":"import npmFetch from 'npm-registry-fetch';\n\nasync function fetchPing() {\n  try {\n    // Basic fetch request to the npm registry ping endpoint\n    const res = await npmFetch('/-/ping', {\n      // Optional: Specify a custom registry, defaults to npmjs.org\n      // registry: 'https://registry.npmjs.org/',\n      // Optional: Pass an AbortSignal for request cancellation\n      // signal: AbortSignal.timeout(5000),\n      // Optional: Authentication token (e.g., from process.env)\n      // token: process.env.NPM_TOKEN ?? '',\n    });\n    console.log('Status:', res.status);\n    console.log('Headers:', res.headers.raw());\n    const data = await res.json(); // Standard Fetch API method to parse JSON body\n    console.log('Body (parsed JSON):', data);\n  } catch (error) {\n    console.error('Failed to fetch via raw response:', error.message);\n  }\n\n  try {\n    // Using the convenience method fetch.json for direct JSON parsing\n    const jsonBody = await npmFetch.json('/-/ping');\n    console.log('\\nUsing npmFetch.json for ping:', jsonBody);\n  } catch (error) {\n    console.error('Failed to fetch via .json helper:', error.message);\n  }\n}\n\nfetchPing();","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to a compatible version (e.g., Node.js 20.17.x or 22.9.x or newer).","message":"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.","severity":"breaking","affected_versions":">=19.0.0"},{"fix":"Upgrade your Node.js environment to a compatible version (e.g., Node.js 18.17.x or 20.5.x or newer).","message":"Version 18.0.0 of `npm-registry-fetch` dropped support for Node.js versions older than `18.17.0 || >=20.5.0`.","severity":"breaking","affected_versions":">=18.0.0 <19.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=17.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The Node.js version installed is older than the minimum required by the `npm-registry-fetch` package.","error":"Error: `npm-registry-fetch` requires Node.js version `^20.17.0 || >=22.9.0`"},{"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.","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.","error":"TypeError: npm_registry_fetch_1.default is not a function"},{"fix":"Refactor your import statements to use ES module syntax: `import npmFetch from 'npm-registry-fetch';`.","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).","error":"ReferenceError: require is not defined in ES module scope"}],"ecosystem":"npm"}