Fixing Exact Package Search Relevance in npmx

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

Project Overview

npmx is an open-source alternative interface for exploring packages from the npm registry. It provides package details, documentation, version history, dependencies, search tools, and other information for JavaScript developers.

Bug Fix or Performance Improvement

I worked on issue #2978, which was reported by another contributor.

When Algolia was selected as the search provider, the page displayed “Relevance” as the active sorting option. However, an exact package-name match did not always appear first.

For example, searching for napkin could show other packages above the exact match. Switching to “Downloads/wk” and then back to “Relevance” changed the results and moved napkin to the top.

I reproduced this behavior locally before investigating the cause.

Code

• Issue #2978
• Pull request: https://github.com/npmx-dev/npmx.dev/pull/3103

Before and after

Before

private-user-images.githubusercontent.com

After

private-user-images.githubusercontent.com

My Improvements

npmx already made an additional Algolia request to check whether a package with the exact searched name existed.

However, this request retrieved only the package name and used the result only as an existence check. If the exact package was missing from the initial batch of results, the application knew it existed but did not have enough information to display it.

I updated the exact-package request to retrieve the complete package information. When the returned package name matches the searched name, it is placed at the beginning of the results.

Before adding it, the code removes any existing occurrence of the same package. This prevents duplicate results.

I also added two safety checks during review:

• A missing Algolia hits array falls back to an empty array.
• A returned hit is promoted only when its name matches the requested package.

Finally, I added a regression test that supplies a regular search result and a separate exact-package result. The test verifies that the exact package is detected and placed first.

I validated the change by running the focused Nuxt tests, TypeScript checks, lint and formatting checks, and by testing the behavior manually in the local UI.

After the fix, an exact package-name match appears at the top immediately when “Relevance” is selected.