docs: document special meaning of registry.npmjs.com

This behavior has been present in npm for a while, but I haven't found where it's documented. This is my attempt at documenting the behavior based on my understanding of it. I think a SME should contribute to this so the documentation is correct. npm/feedback#544 #3783 https://github.com/npm/arborist/blob/478871bf0a44a8ec516b9057585b8707e60b0349/lib/arborist/reify.js#L687-L693 PR-URL: #3784 Credit: @everett1992 Close: #3784 Reviewed-by: @wraithgar
npm · Sep 23, 2021 · dae5ce3 · dae5ce3
1 parent 6535dd9
commit dae5ce3
Show file tree

Hide file tree

Showing 2 changed files with 11 additions and 2 deletions.
diff --git a/docs/content/configuring-npm/package-lock-json.md b/docs/content/configuring-npm/package-lock-json.md
@@ -138,7 +138,8 @@ Package descriptors have the following fields:
   the case of packages fetched from the registry, this will be a url to a
   tarball.  In the case of git dependencies, this will be the full git url
   with commit sha.  In the case of link dependencies, this will be the
-  location of the link target.
+  location of the link target. `registry.npmjs.org` is a magic value meaning
+  "the currently configured registry".
 
 * integrity: A `sha512` or `sha1` [Standard Subresource
   Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/)
@@ -201,7 +202,8 @@ Dependency objects have the following fields:
 
 * resolved: For registry sources this is path of the tarball relative to
   the registry URL.  If the tarball URL isn't on the same server as the
-  registry URL then this is a complete URL.
+  registry URL then this is a complete URL. `registry.npmjs.org` is a magic
+  value meaning "the currently configured registry".
 
 * bundled:  If true, this is the bundled dependency and will be installed
   by the parent module.  When installing, this module will be extracted

diff --git a/docs/content/using-npm/registry.md b/docs/content/using-npm/registry.md
@@ -30,6 +30,13 @@ The registry URL used is determined by the scope of the package (see
 supplied by the `registry` config parameter.  See [`npm config`](/commands/npm-config),
 [`npmrc`](/configuring-npm/npmrc), and [`config`](/using-npm/config) for more on managing npm's configuration.
 
+When the default registry is used in a package-lock or shrinkwrap is 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.
+
 ### Does npm send any information about me back to the registry?
 
 Yes.