libnpmsearch

library9.0.1jsnpmunverified

libnpmsearch is a Node.js library providing a programmatic API for searching packages within the npm registry and compatible alternative registries. Currently stable at version 9.0.1, it is part of the broader npm CLI ecosystem, benefiting from its active maintenance and continuous integration. The library exclusively utilizes the modern npm search endpoint, explicitly *not* supporting legacy `/-/all` search methods. It differentiates itself by offering detailed search parameters, including sorting by quality, maintenance, and popularity, and integrates seamlessly with `npm-registry-fetch` for robust request configuration, authentication, and caching capabilities. Its release cadence is tied to the npm CLI's development, providing regular updates and bug fixes for modern Node.js environments.

devops http-networking data

npm install libnpmsearch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LIBNPMSEARCH

libnpmsearch

devopsjavascriptv9.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import search from 'libnpmsearch'

✗ import { search } from 'libnpmsearch'

The package provides a default export, not a named export. This is the correct ESM import for its CommonJS default export.

✓ const search = require('libnpmsearch')

✗ const { search } = require('libnpmsearch')

This is the canonical CommonJS import pattern, as shown in the package's README, for its default function export.

search.stream

✓ import search from 'libnpmsearch'; const results = await search.stream('react')

✗ import { stream } from 'libnpmsearch'; const results = await stream('react')

The `stream` method is a property of the default `search` function, not a top-level named export.

This quickstart demonstrates how to perform basic and detailed searches using libnpmsearch, including pagination and sorting options. It shows how to retrieve package metadata and score details, highlighting the integration with npm-registry-fetch options like `token`.

import search from 'libnpmsearch'; async function runSearch() { // Search for packages related to 'libnpm' console.log('Searching for "libnpm"...'); const results = await search('libnpm', { limit: 5 }); console.log('Top 5 results for "libnpm":'); results.forEach(pkg => { console.log(`- ${pkg.name}@${pkg.version}: ${pkg.description || 'No description'}`); }); // Search for 'express' with detailed scores and sorted by quality console.log('\nSearching for "express" with detailed scores and quality sort...'); const detailedResults = await search('express', { detailed: true, sortBy: 'quality', limit: 3, // Example of passing options to npm-registry-fetch (e.g., a token if needed) // token: process.env.NPM_TOKEN ?? '' }); console.log('Top 3 quality results for "express":'); detailedResults.forEach(item => { console.log(`- ${item.package.name}@${item.package.version} (Score: ${item.score.final.toFixed(2)})`); console.log(` Description: ${item.package.description || 'N/A'}`); console.log(` Quality: ${item.score.detail.quality.toFixed(2)}, Maintenance: ${item.score.detail.maintenance.toFixed(2)}, Popularity: ${item.score.detail.popularity.toFixed(2)}`); }); } runSearch().catch(console.error);

Debug

Known issues

breakinglibnpmsearch requires Node.js version 20.17.0 or higher, or 22.9.0 or higher. Older Node.js versions are not supported.

fix

Upgrade your Node.js environment to a compatible version (e.g., using nvm or your OS package manager).

affects: >=9.0.0

gotchaThis library explicitly does not support the legacy `/-/all` search endpoint. It uses the modern npm search API.

fix

Ensure your search queries are compatible with the modern npm search endpoint. This typically means using keywords or package names rather than expecting full registry dumps.

affects: >=1.0.0

gotchaMany configuration options (e.g., `token`, `registry`, `ca`, `cert`, `key`) are passed through directly to `npm-registry-fetch`. Users must consult the `npm-registry-fetch` documentation for a complete list and explanation of these options.

fix

Refer to the `npm-registry-fetch` documentation on npmjs.com for a comprehensive guide on fetch options and authentication configurations.

affects: >=1.0.0

gotchaThe `opts.limit` parameter is a suggestion to the API. You might receive slightly more or fewer results than requested, at the registry endpoint's discretion.

fix

Implement client-side logic if an exact number of results is critical, such as filtering or truncating the returned array.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: (0 , libnpmsearch_1.search) is not a function

Attempting to use named import syntax `import { search } from 'libnpmsearch'` when the package provides a default export.

fix

Change your import statement to `import search from 'libnpmsearch';` for ESM, or `const search = require('libnpmsearch');` for CommonJS.

ReferenceError: require is not defined in ES module scope

Using `require()` in a Node.js environment where the current file or project is configured as an ES module (e.g., `"type": "module"` in `package.json`).

fix

Refactor your code to use `import search from 'libnpmsearch';`. If you intend to use CommonJS, ensure your `package.json` does not have `"type": "module"` or change your file extension to `.cjs`.

Error: Registry returned unauthorized for this scope.

Attempting to search a private registry or perform an authenticated search without providing a valid `token` option or having appropriate `.npmrc` configuration.

fix

Pass `opts.token` with a valid authentication token obtained from your registry, or ensure your npm client is logged in to the target registry by running `npm login`.

Upgrade

Version history

9.0.1latest on npm

Audit

Dependencies

npm-registry-fetchrequiredUsed internally for all registry interactions; many configuration options are passed directly to it.

Agent activity

1 hits · last 30 days