search-packages

Search packages on NPM.

Queries the npm registry search API over fetch — no npm binary on PATH, no process spawn — and returns only the packages carrying every keyword you asked for.

Requires Node 18 or later for the global fetch.

Usage

import { searchByKeywords } from 'search-packages'

(async () => {
  const packages = await searchByKeywords(['some-keyword', 'more-keywords']) // ['pkg-a', 'pkg-b']
}())

// get additional fields
(async () => {
  // [{ name: 'pkg-a', description: 'a' }, { name: 'pkg-b', description: 'b' }]
  const packages = await searchByKeywords(['some-keyword', 'more-keywords'], ['description'])
}())

Options

A third argument tunes the request:

await searchByKeywords(['some-keyword'], undefined, {
  registry: 'https://registry.example.com', // defaults to https://registry.npmjs.org
  maxResults: 500,                          // defaults to 1000
  signal: controller.signal,                // aborts the in-flight requests
  fetch: myFetch                            // defaults to the global fetch
})

The result cap

The registry pages results 250 at a time, and a broad keyword can match thousands of packages. Paging all of them would mean dozens of sequential round trips, so searchByKeywords stops after 1000 results (4 requests) by default.

The cap is not silent — fetchPackagesByKeywords returns the same packages plus a truncated flag telling you whether the registry had more:

import { fetchPackagesByKeywords } from 'search-packages'

const { packages, truncated } = await fetchPackagesByKeywords(['some-keyword'])

Pass { maxResults: Number.POSITIVE_INFINITY } to page through everything.

Note that hasAllKeywords filtering happens client-side: the registry's keywords: qualifier matches loosely, so a package matching only some of your keywords still comes back from the API and is dropped here.

Contribute

# after fork and clone
pnpm install

# begin making changes
git checkout -b <branch>
pnpm --filter search-packages watch

# after making change(s)
pnpm verify
git commit -m "<commit message>"
git push

# create PR