From 17c94c46359ef9caebf8a8a29115e6fe6d20b0e5 Mon Sep 17 00:00:00 2001
From: Martin Bergman <martin@devsed.se>
Date: Tue, 11 Feb 2025 18:58:57 +0100
Subject: [PATCH 1/2]  [refs #8095] docs(npmrc): add example of URI fragment
 limitations

 Update formatting for clarity, resolve lint MD040/fenced-code-language and change hostnames to npmjs.org subdomains
---
 docs/lib/content/configuring-npm/npmrc.md | 25 +++++++++++++++--------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/docs/lib/content/configuring-npm/npmrc.md b/docs/lib/content/configuring-npm/npmrc.md
index cd31ae886f132..b17dfd0c0387b 100644
--- a/docs/lib/content/configuring-npm/npmrc.md
+++ b/docs/lib/content/configuring-npm/npmrc.md
@@ -112,23 +112,30 @@ the scope may look like `//registry.npmjs.org/:`. If it must be scoped to a
 specific path on the host that path may also be provided, such as
 `//my-custom-registry.org/unique/path:`.
 
-```
+```ini
 ; bad config
 _authToken=MYTOKEN
 
 ; good config
-@myorg:registry=https://somewhere-else.com/myorg
-@another:registry=https://somewhere-else.com/another
+@myorg:registry=https://somewhere-else.npmjs.org/myorg
+@another:registry=https://somewhere-else.npmjs.org/another
+@anotherorg:registry=https:///registry.npmjs.org/path/anotherorg
+
+; Applies to any registry at https://registry.npmjs.org/ but not to any sub-path (see @anotherorg)
 //registry.npmjs.org/:_authToken=MYTOKEN
 
-; would apply to both @myorg and @another
-//somewhere-else.com/:_authToken=MYTOKEN
+; Applies to both @myorg and @another but noth @anotherorg
+//somewhere-else.npmjs.org/:_authToken=MYTOKEN
+
+; Only applies to @myorg
+//somewhere-else.npmjs.org/myorg/:_authToken=MYTOKEN1
+
+; Only applies to @another
+//somewhere-else.npmjs.org/another/:_authToken=MYTOKEN2
 
-; would apply only to @myorg
-//somewhere-else.com/myorg/:_authToken=MYTOKEN1
+; Only applies to @anotherorg
+//registry.npmjs.org/path/anotherorg:_authToken=MYTOKEN3
 
-; would apply only to @another
-//somewhere-else.com/another/:_authToken=MYTOKEN2
 ```
 
 ### See also

From 289b85ea7c1a1bfef667d5e646d3270ccb74dbc5 Mon Sep 17 00:00:00 2001
From: Martin Bergman <martin@devsed.se>
Date: Sun, 16 Mar 2025 13:05:09 +0100
Subject: [PATCH 2/2] add breakdown of registry and auth config

---
 docs/lib/content/configuring-npm/npmrc.md | 26 ++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/docs/lib/content/configuring-npm/npmrc.md b/docs/lib/content/configuring-npm/npmrc.md
index b17dfd0c0387b..fe3161a819a49 100644
--- a/docs/lib/content/configuring-npm/npmrc.md
+++ b/docs/lib/content/configuring-npm/npmrc.md
@@ -94,7 +94,7 @@ to override default configs in a standard and consistent manner.
 ### Auth related configuration
 
 The settings `_auth`, `_authToken`, `username` and `_password` must all be
-scoped to a specific registry. This ensures that `npm` will never send
+scoped to a specific `registry`. This ensures that `npm` will never send
 credentials to the wrong host.
 
 The full list is:
@@ -112,6 +112,30 @@ the scope may look like `//registry.npmjs.org/:`. If it must be scoped to a
 specific path on the host that path may also be provided, such as
 `//my-custom-registry.org/unique/path:`.
 
+#### How NPM matches Registry URL with auth configuration
+
+Let's say you have:
+
+```ini
+@myorg:registry=https://registry.npmjs.org/myorg
+```
+
+npm will look for:
+
+```ini
+//registry.npmjs.org/myorg/:_authToken=...
+```
+
+If instead you put:
+
+```ini
+//registry.npmjs.org/:_authToken=...
+```
+
+That won’t be used, because it **doesn’t match** what npm looks for from the registry URL you defined.
+
+#### Extended configuration example
+
 ```ini
 ; bad config
 _authToken=MYTOKEN