Skip to content

Files

Latest commit

 

History

History
234 lines (180 loc) · 6.32 KB

README.md

File metadata and controls

234 lines (180 loc) · 6.32 KB

fast-npm-meta

npm version npm downloads bundle JSDocs License

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.

Screenshot of fetching npm registry

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.

Important

This project is still in the early stage of development. Pin your dependencies on usage, and feedback are greatly welcomed.

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": "5.3.2",
  "lastSynced": 1719798752827
}

📦 Get the Latest Version of a Tag

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

Returns

{
  "name": "vite",
  "specifier": "alpha",
  "version": "6.0.0-alpha.18",
  "lastSynced": 1719798752827
}

📦 Get the Latest Version of a Range

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

Returns

{
  "name": "vite",
  "specifier": "^2.1.0",
  "version": "2.9.18",
  "lastSynced": 1719798752827
}

📦 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.18",
    "lastSynced": 1719798752827
  },
  {
    "name": "vue",
    "specifier": "latest",
    "version": "3.4.31",
    "lastSynced": 1719799051285
  },
  {
    "name": "nuxt",
    "specifier": "~3.11",
    "version": "3.11.2",
    "lastSynced": 1719799051232
  }
]

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",
    "0.2.0",
    "0.3.0",
    "0.3.1",
    "0.3.2",
    "0.4.0"
    // ...
  ],
  "lastSynced": 1719801079260
}

📦 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

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

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