Walkthrough

This PR is a documentation-only rewrite across pnpr-docs, replacing the "mounts/defaultTarget/routes" configuration terminology with a "registries/defaultRegistry" model. It updates configuration.md, endpoints.md, cli.md, install-acceleration.md, introduction.md, quick-start.md, and storage.md examples and prose accordingly.

Changes

pnpr-docs terminology migration

Estimated code review effort: 2 (Simple) | ~12 minutes

Possibly related PRs

• pnpm/pnpm.io#829: Added the initial pnpr docs pages for the same files (cli.md, configuration.md, etc.) that this PR rewrites.

Poem

Mounts once stood where registries now grow,
A rabbit hops through docs, row by row,
"sources" and "defaultRegistry" take their place,
No fall-through here, just a tidy namespace,
🐇 Thump-thump — the config docs now glow!

• X
• Mastodon
• Reddit
• LinkedIn

• Document the new registries/defaultRegistry configuration model and routing rules.
• Explain per-registry packages namespaces with specificity-based rule selection and ACL
 semantics.
• Clarify HTTP surface gating (--disable-registry) and always-on login/token endpoints across
 tiers.

graph TD
  A["pnpr.yaml config"] --> B["pnpr server"] --> C["Registry surface"] --> D["/~name/ registry"]
  B --> E["Resolver surface"]
  B --> F["Login/token endpoints"]
  D --> G["Router registry"] --> H["Ordered sources"]

Loading

The PR’s approach—rewriting the docs to describe the redesigned model directly—is appropriate for a pre-1.0 project and keeps the documentation internally consistent (anchors/examples/rules all match the new semantics). Considered adding migration notes for old keys, but that would add noise and split the narrative without benefiting new users.

Documentation (7) +271 / -220

cli.mdClarify --disable-registry semantics under the new surface-gating rules +1/-1

Clarify --disable-registry semantics under the new surface-gating rules

• Rewords '--disable-registry' to reflect that the npm-registry surface is served whenever at least one registry is declared, and that health + login/token endpoints remain available even when the surface is disabled.

pnpr-docs/cli.md

configuration.mdRewrite configuration docs for registries/defaultRegistry, packages maps, and ordered sources +168/-137

Rewrite configuration docs for registries/defaultRegistry, packages maps, and ordered sources

• Renames 'mounts'/'defaultTarget' to 'registries'/'defaultRegistry' and updates all examples accordingly. Adds a dedicated 'packages' map section describing the restricted pattern language, specificity-based selection (order-independent), and per-package access/publish/unpublish defaults. Updates router semantics to ordered 'sources', documents namespace enforcement and denial shapes, and replaces the 'registry.enabled' toggle with derived registry-surface gating plus always-on account endpoints and startup validation.

pnpr-docs/configuration.md

endpoints.mdUpdate HTTP endpoint docs for registries-derived gating and always-on account routes +50/-36

Update HTTP endpoint docs for registries-derived gating and always-on account routes

• Describes registry-surface availability as derived from 'registries' (with '--disable-registry' override) rather than 'registry.enabled'. Updates routing description to ordered 'sources' dispatch and adds explicit namespace enforcement behavior on every path. Documents user/token endpoints as always mounted so 'pnpm login' works even for resolver-only deployments.

pnpr-docs/endpoints.md

install-acceleration.mdAlign install-acceleration docs with registries terminology and always-on login endpoints +13/-11

Align install-acceleration docs with registries terminology and always-on login endpoints

• Replaces legacy 'mount' terminology/anchors with 'registry' equivalents and updates explanations of private package tarball URLs and caching. Adds/clarifies that login/token endpoints remain available even when only the resolver surface is exposed.

pnpr-docs/install-acceleration.md

introduction.mdRefresh overview to match registries + namespace-claim routing model +5/-4

Refresh overview to match registries + namespace-claim routing model

• Updates the introductory explanation to describe declared registries that claim package names and router-based resolution without cross-origin fall-through.

pnpr-docs/introduction.md

quick-start.mdRewrite quick-start example config to use registries, packages maps, and sources +28/-24

Rewrite quick-start example config to use registries, packages maps, and sources

• Updates the narrative and sample 'pnpr.yaml' to the new 'registries'/'defaultRegistry' keys, adds a 'packages' namespace for the hosted registry, and replaces router 'routes' with ordered 'sources' (including the catch-all guidance). Adjusts publish/login explanations to reflect namespace claims and upstream write rejection.

pnpr-docs/quick-start.md

storage.mdUpdate storage backend example configs to the new registry configuration shape +6/-7

Update storage backend example configs to the new registry configuration shape

• Rewrites the S3-backed configuration example to use 'registries', per-registry 'packages' namespace, ordered router 'sources', and 'defaultRegistry' naming.

pnpr-docs/storage.md