query-registry

query-registry is an API wrapper for the npm registry API.

Features

• Provides functions to:
  • Get registry metadata.
  • Get registry public keys.
  • Get packuments (package documents) with full package metadata.
  • Get abbreviated packuments with installation data only.
  • Get package manifests for each version of a package.
  • Get download counts for the registry and for packages.
  • Search packages by name and other specific criteria.
• Works in the browser.
• Validates registry responses with zod.
• Automatically caches registry responses for a short time.
• Supports third-party npm-compatible registries.

Useful resources

• Explore the API on jsDocs.io
• View package contents on unpkg
• View repository on GitHub
• Read the changelog on GitHub

Install

Note

Make sure you have Zod v4 installed in your application to use this package.

Using npm:

npm add zod query-registry

Using yarn:

yarn add zod query-registry

Using pnpm:

pnpm add zod query-registry

Using bun:

bun add zod query-registry

Usage examples

Registry

Get the metadata about the npm registry itself, if available:

import { getRegistryMetadata } from "query-registry";

const metadata = await getRegistryMetadata();

Get the public signing keys for the npm registry:

import { getRegistrySigningKeys } from "query-registry";

const { keys } = await getRegistrySigningKeys();

Packuments (Package documents)

Get the abbreviated packument containing only the necessary data to install the react package:

import { getAbbreviatedPackument } from "query-registry";

const abbrPackument = await getAbbreviatedPackument("react");

Get the full packument containing all the data available about the react package:

import { getPackument } from "query-registry";

const packument = await getPackument("react");

Package manifests

Get the manifest containing the original package.json data plus additional registry metadata for the latest version of the react package:

import { getPackageManifest } from "query-registry";

const manifest = await getPackageManifest("react");

Get the manifest for [email protected] (semver version):

import { getPackageManifest } from "query-registry";

const manifest = await getPackageManifest("react", "18.2.0");

Get the manifest for react@next (distribution tag):

import { getPackageManifest } from "query-registry";

const manifest = await getPackageManifest("react", "next");

Search packages

Search packages related to react (e.g., react, react-dom, ...):

import { searchPackages } from "query-registry";

const results = await searchPackages({ text: "react" });

Download counts

Get the total number of downloads for package react for the last month:

import { getPackageDownloads } from "query-registry";

const { downloads } = await getPackageDownloads("react", "last-month");

There are also these other download counts functions available: getBulkDailyPackageDownloads, getBulkPackageDownloads, getDailyPackageDownloads, getDailyRegistryDownloads and getPackageVersionsDownloads.

Cache

Clear the internal cache.

import { cache } from "query-registry";

cache.clear();

See the quick-lru package for the cache API.

License

MIT

Copyright (c) 2025 Edoardo Scibona

See LICENSE file.