fast-npm-meta

fast-npm-meta

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.

Also, if you try to fetch that metadata from the official pacote library, you will end up pulling 118 dependencies, which sums up to 8.48 MB of files 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

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

Returns

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

Get the Latest Version of a Tag

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

Returns

{
  "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: "^"

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

Returns

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

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

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

Returns

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

Using hyphen: "-"

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

Returns

{
  "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.

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

Returns an array of objects:

[
  {
    "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.

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

{
  "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

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

{
  "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.

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

{
  "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

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

{
  "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.

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.

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

{
  "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.

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

It will return 200 with:

[
  {
    "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.

npm install fast-npm-meta

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.

npm install -g fast-npm-meta

Get the latest version

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

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

fast-npm-meta version vite --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:

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

Get full package metadata

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

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.):

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

Sponsors

License

MIT License 2023-PRESENT Anthony Fu