From 4ccf9f76b2af498118744f3439c2ea0bd11ea20d Mon Sep 17 00:00:00 2001 From: ump45nose Date: Mon, 5 Oct 2026 05:23:34 +0800 Subject: [PATCH 1/3] docs: define "packument" in the registry documentation The term `packument` was used in the CLI documentation (npm-audit, npm-outdated) without ever being defined, so a reader hitting an error message that mentions one - for example "loading from incorrect packument" from the audit code path - has nothing to look it up. Add a short "Packuments" section to the registry page explaining that a packument is the registry's metadata document for a package *name* rather than a version, and link to it from the first use of the term in the npm audit page. Also mention `npx pacote packument --registry=`, which is the direct way to inspect what a registry - including a private one - actually knows about a package. That was the other thing the reporter said would have saved them days of research. Closes: https://github.com/npm/cli/issues/4534 --- docs/lib/content/commands/npm-audit.md | 2 +- docs/lib/content/using-npm/registry.md | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/lib/content/commands/npm-audit.md b/docs/lib/content/commands/npm-audit.md index 737caea05537f..cb5758938f7a7 100644 --- a/docs/lib/content/commands/npm-audit.md +++ b/docs/lib/content/commands/npm-audit.md @@ -54,7 +54,7 @@ for each verified package. The npm CLI supports registry signatures and signing keys provided by any registry if the following conventions are followed: -1. Signatures are provided in the package's `packument` in each published version within the `dist` object: +1. Signatures are provided in the package's [packument](/using-npm/registry#packuments) in each published version within the `dist` object: ```json "dist":{ diff --git a/docs/lib/content/using-npm/registry.md b/docs/lib/content/using-npm/registry.md index 2af6edcd7520a..be29b84f7166c 100644 --- a/docs/lib/content/using-npm/registry.md +++ b/docs/lib/content/using-npm/registry.md @@ -25,6 +25,25 @@ See [Auth Related Configuration](/configuring-npm/npmrc#auth-related-configurati When the default registry is used in a package-lock it has the special meaning of "the currently configured registry". If you create a lock file while using the default registry you can switch to another registry and npm will install packages from the new registry, but if you create a lock file while using a custom registry packages will be installed from that registry even after you change to another registry. +### Packuments + +A **packument** is the JSON document a registry returns for a package *name* rather than for a +specific version. It is the registry's metadata record for the package: its name, description, +maintainers, licence and dist-tags, plus every published version with that version's `dist` +object (tarball URL, integrity hash and, where the registry provides them, signatures). + +When npm resolves `foo@^1.2.0` it fetches the packument for `foo` and picks a version out of +it, so an out-of-date or mismatched packument is a common cause of resolution errors. + +You can fetch a packument for any package yourself: + +``` +npx pacote packument [--registry=] +``` + +That is the quickest way to check what a registry actually knows about a package, and it works +against a private registry as well, for example `--registry=http://localhost:4873`. + ### Does npm send any information about me back to the registry? Yes. From 4b1b432a291d62608ef663b4c1f79283c869a67f Mon Sep 17 00:00:00 2001 From: ump45nose Date: Sat, 10 Oct 2026 17:18:57 +0800 Subject: [PATCH 2/3] docs: tighten the packument description --- docs/lib/content/using-npm/registry.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/lib/content/using-npm/registry.md b/docs/lib/content/using-npm/registry.md index be29b84f7166c..bd0dfe965c981 100644 --- a/docs/lib/content/using-npm/registry.md +++ b/docs/lib/content/using-npm/registry.md @@ -29,11 +29,11 @@ When the default registry is used in a package-lock it has the special meaning o A **packument** is the JSON document a registry returns for a package *name* rather than for a specific version. It is the registry's metadata record for the package: its name, description, -maintainers, licence and dist-tags, plus every published version with that version's `dist` +maintainers, license and dist-tags, plus every published version with that version's `dist` object (tarball URL, integrity hash and, where the registry provides them, signatures). When npm resolves `foo@^1.2.0` it fetches the packument for `foo` and picks a version out of -it, so an out-of-date or mismatched packument is a common cause of resolution errors. +it. You can fetch a packument for any package yourself: From 049d57d7eb71b788f5d45cc1489e12e96726e03c Mon Sep 17 00:00:00 2001 From: ump45nose <52391318+ump45nose@users.noreply.github.com> Date: Fri, 23 Oct 2026 09:48:50 +0800 Subject: [PATCH 3/3] docs: use one sentence per line in added prose Apply the Markdown conventions from #10108 to this PR's new text only. Preserve wording, links, paragraph boundaries, and Markdown structure. Validation: rendered HTML equivalence (whitespace-normalized), text and scope assertions, and whitespace checks. Full npm/docs tests not run locally. AI-assisted formatting update. --- docs/lib/content/using-npm/registry.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/lib/content/using-npm/registry.md b/docs/lib/content/using-npm/registry.md index bd0dfe965c981..b4717f7c37986 100644 --- a/docs/lib/content/using-npm/registry.md +++ b/docs/lib/content/using-npm/registry.md @@ -27,13 +27,10 @@ When the default registry is used in a package-lock it has the special meaning o ### Packuments -A **packument** is the JSON document a registry returns for a package *name* rather than for a -specific version. It is the registry's metadata record for the package: its name, description, -maintainers, license and dist-tags, plus every published version with that version's `dist` -object (tarball URL, integrity hash and, where the registry provides them, signatures). +A **packument** is the JSON document a registry returns for a package *name* rather than for a specific version. +It is the registry's metadata record for the package: its name, description, maintainers, license and dist-tags, plus every published version with that version's `dist` object (tarball URL, integrity hash and, where the registry provides them, signatures). -When npm resolves `foo@^1.2.0` it fetches the packument for `foo` and picks a version out of -it. +When npm resolves `foo@^1.2.0` it fetches the packument for `foo` and picks a version out of it. You can fetch a packument for any package yourself: @@ -41,8 +38,7 @@ You can fetch a packument for any package yourself: npx pacote packument [--registry=] ``` -That is the quickest way to check what a registry actually knows about a package, and it works -against a private registry as well, for example `--registry=http://localhost:4873`. +That is the quickest way to check what a registry actually knows about a package, and it works against a private registry as well, for example `--registry=http://localhost:4873`. ### Does npm send any information about me back to the registry?