# fast-npm-meta

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![bundle][bundle-src]][bundle-href]
[![JSDocs][jsdocs-src]][jsdocs-href]
[![License][license-src]][license-href]

A lightweight API server to get npm package metadata, resolve the latest versions on server, and batch multiple package resolutions in one request.

## Motivation

NPM registry's API is fairly old and not very efficient. For example, requesting https://registry.npmjs.org/vite will make you download `4.38 MB` of data, which represents `36.32 MB` of uncompressed JSON data. This is a lot of data to download just to get the latest version of a single package.

<img width="280" alt="Screenshot of fetching npm registry" src="https://github.com/antfu/antfu/assets/11247099/32a0f8c3-1be9-440f-9cea-2cbfad4a0b47">

Also, if you try to fetch that metadata from the official [`pacote`](https://github.com/npm/pacote) library, you will end up pulling [118 dependencies](https://npmgraph.js.org/?q=pacote), which sums up to [`8.48 MB` of files](https://packagephobia.com/result?p=pacote) saved on your disk.

This project aims to provide a lightweight API server as the proxy, which caches the metadata from the NPM registry and provides a more efficient way to resolve the versions of the packages.

## API Endpoints

An example server is deployed at https://npm.antfu.dev/. You can also deploy your own instance.

### `GET /:pkg`

#### 📦 Get the Latest Version

```sh
curl https://npm.antfu.dev/vite
```

Returns

```json
{
  "name": "vite",
  "specifier": "latest",
  "version": "6.0.6",
  "publishedAt": "2024-12-26T02:23:38.440Z",
  "lastSynced": 1735331047889
}
```

#### 📦 Get the Latest Version of a Tag

```sh
curl https://npm.antfu.dev/vite@alpha
```

Returns

```json
{
  "name": "vite",
  "specifier": "alpha",
  "version": "6.0.0-alpha.24",
  "publishedAt": "2024-09-04T09:15:20.820Z",
  "lastSynced": 1735331047889
}
```

#### 📦 Get the Latest Version of a Range

##### Using caret: "^"

```sh
curl https://npm.antfu.dev/vite@^2.1.0
```

Returns

```json
{
  "name": "vite",
  "specifier": "^2.1.0",
  "version": "2.9.18",
  "publishedAt": "2024-03-24T15:06:20.353Z",
  "lastSynced": 1735496799048
}
```

##### Using comparators: ">=", "<="

```sh
# ⚠️ Remove spaces from semver range
curl https://npm.antfu.dev/vite@>=2<4
```

Returns

```json
{
  "name": "vite",
  "specifier": ">=2 <4",
  "version": "3.2.11",
  "publishedAt": "2024-09-17T07:34:48.227Z",
  "lastSynced": 1772797798068
}
```

##### Using hyphen: "-"

```sh
# ⚠️ Remove spaces from semver range
curl https://npm.antfu.dev/vite@2-4
```

Returns

```json
{
  "name": "vite",
  "specifier": "2 - 4",
  "version": "4.5.14",
  "publishedAt": "2025-04-30T06:00:52.445Z",
  "lastSynced": 1772797798068
}
```

#### 📦 Resolve Multiple Packages

Use `+` to separate the package specs.

```sh
curl https://npm.antfu.dev/vite@alpha+vue+nuxt@~3.11
```

Returns an array of objects:

```json
[
  {
    "name": "vite",
    "specifier": "alpha",
    "version": "6.0.0-alpha.24",
    "publishedAt": "2024-09-04T09:15:20.820Z",
    "lastSynced": 1735496799048
  },
  {
    "name": "vue",
    "specifier": "latest",
    "version": "3.5.13",
    "publishedAt": "2024-11-15T14:48:51.738Z",
    "lastSynced": 1735496870654
  },
  {
    "name": "nuxt",
    "specifier": "~3.11",
    "version": "3.11.2",
    "publishedAt": "2024-04-04T16:10:14.223Z",
    "lastSynced": 1735496870614
  }
]
```

#### 📦 Get Extra Metadata

You can pass `?metadata=true` to get additional metadata about the package, such as `engines`, `deprecated`, etc.

```sh
curl https://npm.antfu.dev/versions/vite@^2.1.0?metadata=true
```

```json
{
  "name": "vite",
  "engines": {
    "node": ">=12.2.0"
  },
  "specifier": "^2.1.0",
  "version": "2.9.18",
  "publishedAt": "2024-03-24T15:06:20.353Z",
  "lastSynced": 1735496799048
}
```

### `GET /versions/:pkg`

#### 📦 Get All Versions and Tags of a Package

```sh
curl https://npm.antfu.dev/versions/vite
```

```jsonc
{
  "name": "vite",
  "distTags": {
    "previous": "5.2.5",
    "alpha": "6.0.0-alpha.18",
    "beta": "5.3.0-beta.2",
    "latest": "5.3.2"
  },
  "versions": [
    "0.1.0",
    "0.1.1",
    "0.1.2"
    // ...
  ],
  "lastSynced": 1719801079260
}
```

#### 📦 Get All Versions Published After a Certain Date

You can pass the `after` query parameter (ISO 8601 date string or timestamp) to only return versions published after a specific point in time.

```sh
curl "https://npm.antfu.dev/versions/vite?after=2025-01-01T00:00:00Z"
```

```jsonc
{
  "name": "vite",
  "specifier": "*",
  "distTags": {
    "alpha": "6.0.0-alpha.24",
    "latest": "6.3.0",
    "previous": "4.5.13",
    "beta": "6.3.0-beta.2"
  },
  "lastSynced": 1744845678674,
  "versions": [
    "6.0.7"
    // ...
  ],
  "time": {
    "6.0.7": "2025-01-02T19:50:46.030Z"
    // ...
  }
}
```

#### 📦 Get Versions satisfies the Version Range

```sh
curl https://npm.antfu.dev/versions/vite@5
```

```jsonc
{
  "name": "vite",
  "distTags": {
    "previous": "5.2.5",
    "alpha": "6.0.0-alpha.18",
    "beta": "5.3.0-beta.2",
    "latest": "5.3.2"
  },
  "versions": [
    "5.0.0",
    "5.0.1",
    "5.0.2"
    // ...
  ],
  "lastSynced": 1719801079260
}
```

#### 📦 Get All Versions and Tags of Multiple Packages

Use `+` to separate the package names.

```sh
curl https://npm.antfu.dev/versions/vite+vue+nuxt
```

This will responses with an array

### 📦 Get Versions with Metadata

Add `?metadata=true` to the URL to get additional metadata about each version, such as `engines`, `deprecated`, etc.

This would also alter the response format. `versions` and `time` will be omitted, and instead a `versionsMeta` object will be returned.

```sh
curl https://npm.antfu.dev/versions/vite?metadata=true
```

```jsonc
{
  "name": "vite",
  "distTags": {
    "previous": "5.2.5",
    "alpha": "6.0.0-alpha.18",
    "beta": "5.3.0-beta.2",
    "latest": "5.3.2"
  },
  "versionsMeta": {
    "5.0.0": {
      "version": "5.0.0",
      "engines": {
        "node": ">=12.0.0"
      },
      "deprecated": "This version is deprecated"
    },
    "5.0.1": {
      "version": "5.0.1",
      "engines": {
        "node": ">=12.0.0"
      }
    }
    // ...
  },
  "lastSynced": 1719801079260
}
```

## Error Handling

By default, the endpoint will return `400` or `500` status codes for errors.

If you want to handle the errors in the payload, or retriving partial query result, set `?throw=false` in the query string.

```sh
curl https://npm.antfu.dev/vite+non-exist?throw=false
```

It will return `200` with:

```json
[
  {
    "name": "vite",
    "specifier": "latest",
    "version": "6.2.3",
    "publishedAt": "2025-03-24T09:51:35.322Z",
    "lastSynced": 1743129342678
  },
  {
    "name": "non-exist",
    "error": "[GET] \"https://registry.npmjs.org/non-exist\": 404 Not Found"
  }
]
```

In the JavaScript API, you can pass `throw: false` in the option.

## JavaScript API

You can also use the JavaScript API to resolve the versions.

```bash
npm install fast-npm-meta
```

```ts
import { getLatestVersion } from 'fast-npm-meta'

const metadata = await getLatestVersion('vite')

console.log(metadata.version) // 5.3.2
```

## CLI

The package ships with a `fast-npm-meta` CLI for quick lookups from the terminal.

```bash
npm install -g fast-npm-meta
```

### Get the latest version

Returns plain text — one version per line, suitable for scripting.

```sh
fast-npm-meta version vite
# 7.3.1
fast-npm-meta version vite@2
# 2.9.18
fast-npm-meta version "nuxt@^3.5"
# 3.5.22
fast-npm-meta version vite nuxt vue
# 7.3.1
# 4.3.1
# 3.5.29
```

### Get version as JSON

```sh
fast-npm-meta version vite --json
```

```json
{
  "name": "vite",
  "specifier": "latest",
  "version": "7.3.1",
  "publishedAt": "2026-01-07T06:07:43.726Z",
  "lastSynced": 1771999110436
}
```

Multiple packages return an array. Include extra metadata (engines, deprecated, provenance, etc.) with `--metadata`:

```sh
fast-npm-meta version vite --json --metadata
```

### Get full package metadata

Returns the full versions list, dist-tags, and timestamps as JSON.

```sh
fast-npm-meta full vite
fast-npm-meta full vite nuxt vue  # returns an array
```

Add `--metadata` to include per-version metadata (`engines`, `deprecated`, `integrity`, etc.):

```sh
fast-npm-meta full vite --metadata
```

## Configuration

The tool does not require any preliminary configuration to work, but you can override some default parameters through [environment variables or .env files](https://nitro.build/guide/configuration). The main ones:

| Option                | Description                      | Default                                |
|-----------------------|----------------------------------|----------------------------------------|
| `PORT`                | Port to listen on                | `3000`                                 |
| `HOST`                | Host to serve                    |                                        |
| `REPO_URL`            | Code repository URL              | https://github.com/antfu/fast-npm-meta |
| `CACHE_TIMEOUT`       | Cache timeout in ms              | `900000` (15m)                         |
| `CACHE_TIMEOUT_FORCE` | Cache timeout for forced updates | `30000` (30s)                          |
| `REGISTRY_URL`        | NPM registry URL                 | https://registry.npmjs.org             |
| `REGISTRY_USER_AGENT` | User agent for NPM registry requests | `get-npm-meta`                         |

For more information, follow [the official Nitro guides](https://nitro.build/deploy/runtimes/node#environment-variables).

## Sponsors

<p align="center">
  <a href="https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg">
    <img src='https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg' alt='Sponsors' />
  </a>
</p>

## License

[MIT](./LICENSE) License © 2023-PRESENT [Anthony Fu](https://github.com/antfu)

<!-- Badges -->

[npm-version-src]: https://img.shields.io/npm/v/fast-npm-meta?style=flat&colorA=080f12&colorB=1fa669
[npm-version-href]: https://npmjs.com/package/fast-npm-meta
[npm-downloads-src]: https://img.shields.io/npm/dm/fast-npm-meta?style=flat&colorA=080f12&colorB=1fa669
[npm-downloads-href]: https://npmjs.com/package/fast-npm-meta
[bundle-src]: https://img.shields.io/bundlephobia/minzip/fast-npm-meta?style=flat&colorA=080f12&colorB=1fa669&label=minzip
[bundle-href]: https://bundlephobia.com/result?p=fast-npm-meta
[license-src]: https://img.shields.io/github/license/antfu/fast-npm-meta.svg?style=flat&colorA=080f12&colorB=1fa669
[license-href]: https://github.com/antfu/fast-npm-meta/blob/main/LICENSE
[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
[jsdocs-href]: https://www.jsdocs.io/package/fast-npm-meta