NPM Registry Client (Forked and Maintained)

0.3.2 · maintenance · verified Tue Apr 21

@qiwi/npm-registry-client is a fork of the original `npm-registry-client` package, providing a programmatic interface to interact with the npm registry. It was created to address and fix numerous vulnerabilities present in the upstream package and update its dependencies to a more current state (circa 2020), while also introducing TypeScript typings for improved developer experience. The current stable version is 8.9.1, though its last publish date was approximately five years ago, indicating a maintenance-oriented release cadence rather than active feature development. Key differentiators include its explicit focus on security fixes and type definitions compared to the original `npm-registry-client`, which is now largely unmaintained. It allows applications to fetch package metadata, handle authentication, and perform various registry operations such as retrieving package information.

Common errors

```
Error: Cannot find module 'anonymous-npm-registry-client'
```
cause Attempting to `require` or `import` the old, deprecated package name (`anonymous-npm-registry-client` or `npm-registry-client`) after installing `@qiwi/npm-registry-client`.

fix Update your package installation command to `npm install @qiwi/npm-registry-client` or `yarn add @qiwi/npm-registry-client`, and change all import/require statements in your code to `@qiwi/npm-registry-client`.
```
TypeError: RegClient is not a constructor
```
cause Incorrectly importing a CommonJS default export in an ESM context or vice-versa, or attempting `new RegClient()` on something that isn't the constructor function.

fix For CommonJS, use `const RegClient = require('@qiwi/npm-registry-client')`. For ESM/TypeScript, use `import RegClient from '@qiwi/npm-registry-client'` and ensure `"esModuleInterop": true` in your `tsconfig.json`.
```
Error: socket hang up / Error: read ECONNRESET / ETIMEDOUT
```
cause These are common network-related errors, often indicating problems with connectivity, proxy configuration, DNS resolution, or registry server instability, potentially due to long-running requests or insufficient timeouts.

fix Check your internet connection, verify proxy configurations in the `RegClient` constructor's `config` object, and consider increasing the `timeout` parameter in your request `params`. For persistent issues, try a different registry URL or consult network logs.

Warnings

breaking This package, `@qiwi/npm-registry-client`, is a security-focused fork. The original `npm-registry-client` and any other unmaintained derivatives (like `anonymous-npm-registry-client`) are likely abandoned, vulnerable, and should NOT be used. Always ensure you are installing and importing `@qiwi/npm-registry-client`.
Fix: Migrate your project to use `@qiwi/npm-registry-client` (version 8.9.1 or newer if available) and update all `require`/`import` statements to refer to the `@qiwi` scoped package.
gotcha The package is primarily published as a CommonJS module. While TypeScript projects can use ESM `import` syntax, direct ESM runtime support without a bundler or Node.js's `esModuleInterop` for CJS compatibility might be inconsistent as the `package.json` does not declare `module` or `exports` fields for native ESM.
Fix: For pure ESM environments, consider wrapping the `require` call in a custom ESM module or using a bundler (e.g., Webpack, Rollup, esbuild). For TypeScript, ensure `"esModuleInterop": true` is enabled in `tsconfig.json` for seamless `import RegClient from ...`.
gotcha Proper error handling in callbacks is essential. Network requests can fail due to various reasons like timeouts, invalid URIs, or registry errors. The callback's `error` parameter should always be checked and handled.
Fix: Always include `if (error) { /* handle error */ return; }` at the beginning of your callback functions. Differentiate error types (e.g., `error.statusCode` for HTTP errors like 404, `error.code` for network errors like `ETIMEDOUT`) for robust error reporting.
gotcha Authentication is critical for publishing packages, installing from private registries, or performing other protected registry operations. Omitting credentials (token, username/password, email) in the client's configuration object will result in unauthorized access errors for these actions.
Fix: Provide necessary authentication details (e.g., `token`, `username`, `password`, `email`) in the `config` object when initializing `RegClient`. For security, use environment variables (`process.env.NPM_TOKEN`) for sensitive data in production environments.

Install

npm install anonymous-npm-registry-client npm
yarn add anonymous-npm-registry-client yarn
pnpm add anonymous-npm-registry-client pnpm

Imports

RegClient (CommonJS)
```
const RegClient = require('@qiwi/npm-registry-client')
```
This is the documented and primary way to import the client in Node.js environments. Ensure you are using the correct `@qiwi` scoped package name, not `anonymous-npm-registry-client` or `npm-registry-client`.
RegClient (TypeScript ESM)
wrong:
```
import { RegClient } from '@qiwi/npm-registry-client'
```
correct:
```
import RegClient from '@qiwi/npm-registry-client'
```
While the quickstart shows `require`, modern TypeScript projects can use a default `import`. The package is primarily a CommonJS package (`main` field in `package.json`), so direct ESM runtime support without a bundler or `esModuleInterop` in `tsconfig.json` might be inconsistent.
RegClient (Type Import)
```
import type RegClient from '@qiwi/npm-registry-client'
```
For TypeScript projects, the package ships with its own type definitions, allowing for proper type inference.

Quickstart

Demonstrates how to initialize the client, configure it for the npm registry, and fetch package metadata (specifically for 'react') using the `get` method, including basic error handling.

import RegClient from '@qiwi/npm-registry-client';

const config = {
  // Required for authenticated operations, e.g., publishing or private registry access.
  // token: process.env.NPM_TOKEN ?? '',
  // username: process.env.NPM_USERNAME ?? '',
  // password: process.env.NPM_PASSWORD ?? '',
  // email: process.env.NPM_EMAIL ?? '',
  
  registry: 'https://registry.npmjs.org/', // Default npm registry URL
  // cache: '/tmp/npm-cache', // Optional: path to cache directory
  // proxy: { http: 'http://my.proxy.com', https: 'http://my.proxy.com' } // Configure proxy if needed
};

const client = new RegClient(config);
const packageName = 'react'; // Example: Fetch metadata for 'react'
const uri = `${config.registry}${packageName}`;
const params = { timeout: 5000 }; // Request timeout in milliseconds

client.get(uri, params, function (error, data, raw, res) {
  if (error) {
    console.error('Failed to fetch package data:', error.message);
    if (error.statusCode === 404) {
      console.error(`Package '${packageName}' not found. Check the package name and registry.`);
    } else if (error.code === 'ETIMEDOUT') {
      console.error('Request timed out. Consider increasing the timeout or checking network.');
    }
    return;
  }

  console.log(`Successfully fetched metadata for ${packageName}@${data['dist-tags'].latest}`);
  console.log('Latest version description:', data.description);
  // console.log('Raw JSON (truncated):', raw.substring(0, 200) + '...'); // The raw JSON string
  // console.log('HTTP Response Status:', res.statusCode); // The full HTTP response object
});

view raw JSON →