# query-registry

> Query the npm registry for packuments, manifests, packages and download counts

Latest version **4.3.0** (published 2026-03-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install query-registry
pnpm add query-registry
yarn add query-registry
bun add query-registry
```

## Health

**Score 65/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.3.0 |
| Published | 2026-03-06 |
| First published | 2020-07-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=20 |
| Dependencies | 5 |
| Unpacked size | 80 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 33 |
| Author | Edoardo Scibona |
| Maintainers | velut |
| Keywords | api, client, downloads, manifest, npm, package, packument, query, registry, search, typescript |

## Links

- npm: https://www.npmjs.com/package/query-registry
- Repository: https://github.com/velut/query-registry
- Homepage: https://github.com/velut/query-registry#readme
- Issues: https://github.com/velut/query-registry/issues
- npm.io page: https://npm.io/package/query-registry

## Dependencies (5)

- [url-join](https://npm.io/package/url-join.md) ^5.0.0
- [quick-lru](https://npm.io/package/quick-lru.md) ^7.1.0
- [query-string](https://npm.io/package/query-string.md) ^9.2.2
- [zod-package-json](https://npm.io/package/zod-package-json.md) ^2.1.0
- [validate-npm-package-name](https://npm.io/package/validate-npm-package-name.md) ^7.0.2

## Alternatives

- [gamedig](https://npm.io/package/gamedig.md) — 29.3K weekly downloads
- [join-monster](https://npm.io/package/join-monster.md) — 12.8K weekly downloads
- [masked](https://npm.io/package/masked.md) — 5.5K weekly downloads
- [@comunica/actor-query-process-explain-logical](https://npm.io/package/@comunica/actor-query-process-explain-logical.md) — 4.7K weekly downloads
- [@veracity/vui](https://npm.io/package/@veracity/vui.md) — 4.6K weekly downloads

## Recent versions

- 4.3.0 (latest) — 2026-03-06
- 3.0.0-1 (next) — 2024-04-23
- 4.2.0 — 2025-08-26
- 4.1.0 — 2025-06-16
- 4.0.1 — 2025-03-31
- 4.0.0 — 2025-01-20
- 3.0.1 — 2024-06-12
- 3.0.0 — 2024-04-23
- 3.0.0-0 — 2024-04-22
- 2.6.0 — 2022-08-13
- 2.5.0 — 2022-05-28
- 2.5.0-0 — 2022-05-26
- 2.4.0 — 2022-05-11
- 2.3.0 — 2022-04-27
- 2.3.0-0 — 2022-04-25
- … 15 more at https://npm.io/package/query-registry/versions

## README

# query-registry

[![Build status](https://img.shields.io/github/actions/workflow/status/velut/query-registry/main.yml?branch=main)](https://github.com/velut/query-registry/actions?query=workflow%3ACI)
[![Coverage](https://img.shields.io/codecov/c/gh/velut/query-registry)](https://codecov.io/gh/velut/query-registry)
[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/query-registry)
![Language](https://img.shields.io/github/languages/top/velut/query-registry)
[![npm](https://img.shields.io/npm/v/query-registry)](https://www.npmjs.com/package/query-registry)
[![License](https://img.shields.io/github/license/velut/query-registry)](https://github.com/velut/query-registry/blob/main/LICENSE)

`query-registry` is an API wrapper for the [npm registry API](https://github.com/npm/registry/blob/master/docs/REGISTRY-API.md).

## 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](https://www.npmjs.com/package/zod).
- Automatically caches registry responses for a short time.
- Supports third-party npm-compatible registries.

## Useful resources

- [**Explore the API on jsDocs.io**](https://www.jsdocs.io/package/query-registry)
- View package contents on [**unpkg**](https://unpkg.com/query-registry/)
- View repository on [**GitHub**](https://github.com/velut/query-registry)
- Read the changelog on [**GitHub**](https://github.com/velut/query-registry/blob/main/CHANGELOG.md)

## 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:

```typescript
import { getRegistryMetadata } from "query-registry";

const metadata = await getRegistryMetadata();
```

Get the public signing keys for the npm registry:

```typescript
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:

```typescript
import { getAbbreviatedPackument } from "query-registry";

const abbrPackument = await getAbbreviatedPackument("react");
```

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

```typescript
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:

```typescript
import { getPackageManifest } from "query-registry";

const manifest = await getPackageManifest("react");
```

Get the manifest for `react@18.2.0` (semver version):

```typescript
import { getPackageManifest } from "query-registry";

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

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

```typescript
import { getPackageManifest } from "query-registry";

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

### Search packages

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

```typescript
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:

```typescript
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.

```typescript
import { cache } from "query-registry";

cache.clear();
```

See the [quick-lru](https://www.npmjs.com/package/quick-lru) package for the cache API.

## License

```
MIT
```

Copyright (c) 2025 Edoardo Scibona

See [LICENSE](./LICENSE) file.

---
_Source: https://npm.io/package/query-registry · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._