NPM Registry Client (Forked and Maintained)

0.3.2 verified Tue Apr 21 auth: no javascript maintenance

@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 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.

error 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 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

yarn add anonymous-npm-registry-client

pnpm add anonymous-npm-registry-client

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