chore: expand keywords toward real search intent - #20
Merged
Conversation
Measured against npm's search API the package already ranks #1 for naija-id (score 678 vs 71 for the runner-up), #1 for vnin, #3 for bvn and #8 for nuban. So exact-name and single-identifier search already work — the gap is multi-word intent phrases: 'nin nigeria', 'nigerian bank code', 'nigeria kyc', 'voters card nigeria', 'nigerian plate number' were all absent from the top 20. Part of that cannot be fixed with metadata. npm weights popularity heavily, so a days-old package will not outrank libphonenumber-js on a generic phrase like 'phone validation', and pretending otherwise would be keyword stuffing. But several of those phrases failed on words that were simply missing: 'nigerian' (only 'nigeria' was present), 'validator' (only 'validation'), and the spelled-out identifier names. Adds 15 keywords and keeps all 22 existing ones. Separately, the GitHub repo had NO description, NO homepage and NO topics — the largest free win here, since topics feed GitHub search and the description is what Google has to index. Set directly on the repo (19 topics); no release needed for that part.
lintdeveloper
added a commit
that referenced
this pull request
Aug 4, 2026
The expansion two releases ago pushed the wrong way. Measuring the 'nuban' result set (n=14 packages all carrying the term in their description), search score correlates NEGATIVELY with keyword count (-0.24), description length (-0.30) and how late the term appears in the description (-0.29) — the signature of TF-IDF field-length normalisation. Every extra keyword dilutes the ones that matter. For scale, #1 'nuban' carries 2 keywords and a 47-char description; we carried 37 and 186. No measured harm was done (nuban was #8 before the expansion and #8 after), so this is a course correction, not a bug fix. Kept the ten terms that measurably rank or are high-intent: vnin (#1), rsa-pin (#2), bvn (#3), naija (#5), nuban (#8), nin (#10), cac (#20), tin (#29), plus tax-id and nigeria. Dropped 27 that returned NO ranking when tested directly — kyc, pii, redaction, identity, e164, msisdn, phone, plate, passport, validation, validator and the spelled-out variants. They sit in crowded generic fields where name-token matching decides the outcome, so they contributed dilution and nothing else. Description deliberately unchanged: front-loading identifier names would improve term position, but it is the human-facing line on the npm page, and trading readability for a couple of positions on a query where the exact-name package outscores us 13x is a bad deal.
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First, the premise needs correcting
npm search does find this package. Measured against the registry search API right now:
naija-idvninbvnnubanSo exact-name and single-identifier search already work. If it looked missing, that was almost certainly timing — the first publish was 2026-08-02, and npm's search index and the website's cache both lag the registry by minutes to hours.
npm viewserved stale metadata for several minutes after the 0.5.1 publish too.What genuinely does not work
Multi-word intent phrases — none of these had it in the top 20:
Two different causes, and only one is fixable here.
Unfixable by metadata: npm weights popularity heavily. The packages ranking for "nigerian phone validation" are
yup-phone,libphonenumber-js,react-phone-number-input— generic phone libraries with enormous download counts. A days-old package with near-zero downloads will not outrank them, and stuffing keywords to try would just make the listing worse.Fixable: several of those phrases failed on words that were simply absent from the keyword set —
nigerian(onlynigeriawas there),validator(onlyvalidation), and the spelled-out identifier names.Changes
15 keywords added, all 22 existing ones kept:
nigerian,validator,national-identity-number,bank-verification-number,virtual-nin,account-number,bank-account-validation,voters-card,vin,drivers-licence,fixed-line,landline,phone-validation,data-masking,log-redaction.The GitHub repo metadata was empty — no description, no homepage, no topics. That was the largest free win and it's already applied directly to the repo (no release needed):
Topics feed GitHub's own search — where a lot of developers actually look — and the description is what Google has to index. Both were blank.
On Google specifically
Nothing in this PR will move Google, and I'd rather say so than imply otherwise.
npmjs.com/package/naija-idis two days old. Google needs to crawl it, and ranking follows inbound links, which this package has none of yet. That is time and promotion, not metadata:Changeset is
patch— keywords ship inpackage.json, so they need a release to reach npm.