Class NpmClient

Main entry point for the npm Registry API client.

Example

import { NpmClient } from 'npmjs-api-client';

const npm = new NpmClient();

// Get full package metadata
const pkg = await npm.package('react');

// Get a specific version
const v18 = await npm.package('react').version('18.2.0');

// Get the latest version
const latest = await npm.package('react').latest();

// Get dist-tags
const tags = await npm.package('react').distTags();

// Search packages
const results = await npm.search({ text: 'react hooks', size: 10 });

// Get download stats
const stats = await npm.package('react').downloads('last-week');

// Get all packages by a maintainer
const result = await npm.maintainer('sindresorhus').packages();

Constructors

constructor

Methods

downloadRange downloads maintainer on package search

Constructors

constructor

Methods

downloadRange

  • downloadRange(
        period: NpmDownloadPeriod,
        packageName: string,
        signal?: AbortSignal,
    ): Promise<NpmDownloadRange>

    Fetches the per-day download breakdown for a package over a given period.

    GET /downloads/range/{period}/{package} (via api.npmjs.org)

    Convenience method — equivalent to npm.package(name).downloadRange(period).

    Parameters

    • period: NpmDownloadPeriod

      Named period or date range

    • packageName: string

      The package name

    • Optionalsignal: AbortSignal

      Optional AbortSignal to cancel the request

    Returns Promise<NpmDownloadRange>

    Download range data with a per-day array

    Example

    const range = await npm.downloadRange('last-month', 'react');
    range.downloads.forEach(d => console.log(d.day, d.downloads));

downloads

  • downloads(
        period: NpmDownloadPeriod,
        packageName: string,
        signal?: AbortSignal,
    ): Promise<NpmDownloadPoint>

    Fetches the total download count for a package over a given period.

    GET /downloads/point/{period}/{package} (via api.npmjs.org)

    Convenience method — equivalent to npm.package(name).downloads(period).

    Parameters

    • period: NpmDownloadPeriod

      Named period or date range

    • packageName: string

      The package name

    • Optionalsignal: AbortSignal

      Optional AbortSignal to cancel the request

    Returns Promise<NpmDownloadPoint>

    Download point data including total count and date range

    Example

    const stats = await npm.downloads('last-week', 'react');
    console.log(stats.downloads);

maintainer

  • maintainer(username: string): MaintainerResource

    Returns a MaintainerResource for a given npm username, providing access to all packages they maintain.

    GET /-/v1/search?text=maintainer:{username}

    Parameters

    • username: string

      The npm username (e.g. 'sindresorhus', 'pilmee')

    Returns MaintainerResource

    A maintainer resource with a packages() method

    Example

    const result = await npm.maintainer('sindresorhus').packages();
    console.log(`${result.total} packages`);
    result.objects.forEach(o => console.log(o.package.name, o.package.version));

    // Paginate
    const page2 = await npm.maintainer('sindresorhus').packages({ size: 25, from: 25 });

on

  • on<K extends "request">(event: K, callback: NpmClientEvents[K]): this

    Subscribes to a client event.

    Type Parameters

    • K extends "request"

    Parameters

    Returns this

    Example

    npm.on('request', (event) => {
      console.log(`${event.method} ${event.url} — ${event.durationMs}ms`);
      if (event.error) console.error('Request failed:', event.error);
    });

package

  • package(name: string): PackageResource

    Returns a PackageResource for a given package name, providing access to package metadata, versions, dist-tags, and download statistics.

    The returned resource can be awaited directly to fetch the full packument, or chained to access nested resources.

    Parameters

    • name: string

      The package name (e.g. 'react', '@types/node')

    Returns PackageResource

    A chainable package resource

    Example

    const pkg  = await npm.package('react');
    const v18  = await npm.package('react').version('18.2.0');
    const tags = await npm.package('react').distTags();

search

  • search(params: NpmSearchParams, signal?: AbortSignal): Promise<NpmSearchResult>

    Searches for packages on the npm registry.

    GET /-/v1/search

    Parameters

    • params: NpmSearchParams

      Search parameters (required: text)

    • Optionalsignal: AbortSignal

      Optional AbortSignal to cancel the request

    Returns Promise<NpmSearchResult>

    Search results including packages, scores, and total count

    Example

    const results = await npm.search({ text: 'react state management', size: 5 });
    results.objects.forEach(o => console.log(o.package.name, o.package.version));

Settings

Member Visibility

On This Page

Constructors
Methods