🏷️ Discussion Type

Bug

Body

"Package name too similar to existing package": the actual rule is not documented and cannot be checked before publish

What happened

I took a package to the point of release under the name md-render: repository, README, badges, CI, docs, a git tag, GitHub topics, an ESM/CJS build. npm publish failed at the last step:

npm error code E403
npm error 403 403 Forbidden - PUT https://registry.npmjs.org/md-render - Package name too similar to existing package mdrender; try renaming your package to '@bug3/md-render' and publishing with 'npm publish --access=public' instead

The package that blocks it, mdrender, published its last release (1.0.2) in July 2013, and its description on the registry reads ERROR: No README.md file found!.

Nothing npm provides on the way to publish warns about this:

Third-party tooling inherits the blindness: can-npm-publish exits 0 too. The one tool that does flag the name, npm-name (about 150k weekly downloads), can do so only because the rule was reverse-engineered into it from the 2018 blog post quoted below, and the reverse-engineered version is incomplete.

So the check that decides the outcome runs after every other decision has been made and written down: the repository name, the package name in every code example, import paths, badge URLs, CI config, git tags, and the install line other people may already have copied. In my case the recovery meant renaming the package, the GitHub repository, the tag, and every reference in docs and CI; it now ships as prompt-render.

The rule is documented ambiguously, and the natural reading is wrong

The package name guidelines require that an unscoped name "is not spelled in a similar way to another package name", and never define similar. The closest thing to a definition is the 2018 moniker rules post:

"If you are publishing a new package [...] we remove punctuation from its name and compare it to existing package names. If the names are identical without punctuation, we do not allow the package to be created."

The first sentence removes punctuation from one name only: the new one. Whether existing names are also normalised is left to the reader, and npm-name implemented the one-sided reading.

That reading is wrong. I tested the registry with a throwaway pair of names; the one that published has since been unpublished:

1. Published bug3.preflight-probe.
2. Attempted to publish bug3-preflight-probe while the first was live:

npm error code E403
npm error 403 403 Forbidden - PUT https://registry.npmjs.org/bug3-preflight-probe - Package name too similar to existing package bug3.preflight-probe; try renaming your package to '@bug3/bug3-preflight-probe' and publishing with 'npm publish --access=public' instead

The existing punctuated name blocked the new one, so both sides are normalised. This is not a corner case: it means lodash-merge is unpublishable because lodash.merge exists, and nothing documents that. Learning it required publishing a package to the public registry, because there is no other way to observe the rule.

And punctuation is not even the whole rule. A 2024 report shows the registry blocking noxe as too similar to node, which no punctuation stripping explains. Whatever check did that appears in no documentation at all.

What I am asking for

Not the removal of the rule. Typosquat prevention is worth having. In ascending order of cost:

1. Make the documentation state the rule. The name guidelines say "similar" without defining it, and the 2018 post defines only the punctuation part, one-sidedly. State what is actually checked: at minimum, that punctuation is stripped from both the new name and the existing names before comparing, plus whatever blocked noxe.
2. Say it on the npmjs.com 404 page. "This name is unused, but it cannot be published because it is too similar to mdrender."
3. Run the same validation in npm publish --dry-run, so the failure happens before the release, not during it.
4. Expose the check: a documented endpoint, or a CLI command, that answers "can I publish this name?" without publishing.

Why tooling cannot close this gap alone

The likely collisions are cheap to find from outside. Checking the spellings that share the candidate's own word boundaries is four requests, and finds mdrender in under a second:

// md-render -> mdrender, md-render, md_render, md.render
const parts = name.toLowerCase().split(/[-._]/);
const variants = ['', '-', '_', '.'].map(separator => parts.join(separator));
// then HEAD https://registry.npmjs.org/<variant> for each

I have sent that check to npm-name.

A complete check is impossible from outside. Any existing name whose stripped form matches can block, and for a name with no punctuation the cheap check has nothing to vary: lodashmerge is blocked by lodash.merge, and finding that means trying every way to re-insert separators, which is 4^(n-1) spellings, about a million for an 11-character name. The registry has no endpoint that answers which existing names strip down to a given string, and the search API is not a substitute: it happens to surface lodash.merge for lodashmerge, but a search for socketio does not return socket.io. Only the registry can answer "can this name be published", which is why item 4 is the only complete fix.

A note on the rule's reach

A package whose last release is thirteen years old and whose registry description is an error string blocks an entire family of names, and the error message offers only a scope as a way out. That is by policy: the disputes policy states that "npm does not resolve squatting claims on demand", and the only documented path is trademark-based. If the similarity rule keeps this reach, a documented path for releasing long-abandoned names would help.

Prior art

• npm/www#312 (2018): the website showed publish instructions for names that cannot be published. Today the page is a plain 404, which still gives no hint that the name is blocked. The issue was never resolved, and that repository is now archived.
• sindresorhus/npm-name-cli#10 (2018): a user reported exactly this, a name shown as available that npm publish rejects. It was closed within minutes, and a punctuation check only reached npm-name in 2026, reverse-engineered from the blog post.
• sindresorhus/npm-name#48 (2024): the same error reported against the tool again; it stayed open until that punctuation check shipped. The maintainer's summary while closing it: "npm checks for similar package names server-side and they have not published exactly what they check for."

The gap was reported eight years ago. It is still the first wall a new publisher hits, and the documentation still does not say how the rule actually works.