{"id":13441,"library":"libnpmsearch","title":"npm Registry Search API","description":"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.","status":"active","version":"9.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/npm/cli","tags":["javascript","npm","search","api","libnpm"],"install":[{"cmd":"npm install libnpmsearch","lang":"bash","label":"npm"},{"cmd":"yarn add libnpmsearch","lang":"bash","label":"yarn"},{"cmd":"pnpm add libnpmsearch","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for all registry interactions; many configuration options are passed directly to it.","package":"npm-registry-fetch","optional":false}],"imports":[{"note":"The package provides a default export, not a named export. This is the correct ESM import for its CommonJS default export.","wrong":"import { search } from 'libnpmsearch'","symbol":"search","correct":"import search from 'libnpmsearch'"},{"note":"This is the canonical CommonJS import pattern, as shown in the package's README, for its default function export.","wrong":"const { search } = require('libnpmsearch')","symbol":"search","correct":"const search = require('libnpmsearch')"},{"note":"The `stream` method is a property of the default `search` function, not a top-level named export.","wrong":"import { stream } from 'libnpmsearch'; const results = await stream('react')","symbol":"search.stream","correct":"import search from 'libnpmsearch'; const results = await search.stream('react')"}],"quickstart":{"code":"import search from 'libnpmsearch';\n\nasync function runSearch() {\n  // Search for packages related to 'libnpm'\n  console.log('Searching for \"libnpm\"...');\n  const results = await search('libnpm', { limit: 5 });\n  console.log('Top 5 results for \"libnpm\":');\n  results.forEach(pkg => {\n    console.log(`- ${pkg.name}@${pkg.version}: ${pkg.description || 'No description'}`);\n  });\n\n  // Search for 'express' with detailed scores and sorted by quality\n  console.log('\\nSearching for \"express\" with detailed scores and quality sort...');\n  const detailedResults = await search('express', { \n    detailed: true, \n    sortBy: 'quality', \n    limit: 3,\n    // Example of passing options to npm-registry-fetch (e.g., a token if needed)\n    // token: process.env.NPM_TOKEN ?? '' \n  });\n  console.log('Top 3 quality results for \"express\":');\n  detailedResults.forEach(item => {\n    console.log(`- ${item.package.name}@${item.package.version} (Score: ${item.score.final.toFixed(2)})`);\n    console.log(`  Description: ${item.package.description || 'N/A'}`);\n    console.log(`  Quality: ${item.score.detail.quality.toFixed(2)}, Maintenance: ${item.score.detail.maintenance.toFixed(2)}, Popularity: ${item.score.detail.popularity.toFixed(2)}`);\n  });\n}\n\nrunSearch().catch(console.error);","lang":"typescript","description":"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`."},"warnings":[{"fix":"Upgrade your Node.js environment to a compatible version (e.g., using nvm or your OS package manager).","message":"libnpmsearch requires Node.js version 20.17.0 or higher, or 22.9.0 or higher. Older Node.js versions are not supported.","severity":"breaking","affected_versions":">=9.0.0"},{"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.","message":"This library explicitly does not support the legacy `/-/all` search endpoint. It uses the modern npm search API.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the `npm-registry-fetch` documentation on npmjs.com for a comprehensive guide on fetch options and authentication configurations.","message":"Many 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement client-side logic if an exact number of results is critical, such as filtering or truncating the returned array.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import search from 'libnpmsearch';` for ESM, or `const search = require('libnpmsearch');` for CommonJS.","cause":"Attempting to use named import syntax `import { search } from 'libnpmsearch'` when the package provides a default export.","error":"TypeError: (0 , libnpmsearch_1.search) is not a function"},{"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`.","cause":"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`).","error":"ReferenceError: require is not defined in ES module scope"},{"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`.","cause":"Attempting to search a private registry or perform an authenticated search without providing a valid `token` option or having appropriate `.npmrc` configuration.","error":"Error: Registry returned unauthorized for this scope."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}