Registry access

@modularityjs/* packages publish to a private npm registry at https://npm.modularityjs.com/. Before any pnpm install, pnpm dlx, or npx @modularityjs/* resolves, npm needs two pieces of configuration: which registry serves the scope, and how to authenticate to it. The first belongs in the project (commit it); the second belongs in your home directory (never commit it).

Project-level .npmrc — commit this

Put the registry mapping in a .npmrc at your project root:

engine-strict=true
@modularityjs:registry=https://npm.modularityjs.com/
//npm.modularityjs.com/:always-auth=true

Commit the file. It tells every collaborator's pnpm where to fetch the scope from, and forces auth on every request (so an unauthenticated install fails fast with a clear error instead of falling through to the public registry).

@modularityjs/create writes this .npmrc for you automatically — new projects are wired up out of the box.

Personal credentials in ~/.npmrc — do not commit

Append the _auth line to your home directory's .npmrc:

//npm.modularityjs.com/:_auth=<base64(username:password)>

The value is username:password base64-encoded:

printf '%s' "your-username:your-password" | base64

Or use npm login, which writes the line for you:

npm login --scope=@modularityjs --registry=https://npm.modularityjs.com/

Never put _auth (or _authToken) in the project-level .npmrc. A leaked credential in git history is hard to revoke cleanly. Keep auth in ~/.npmrc; keep the registry mapping in the project.

CI

CI runners have no ~/.npmrc, so the auth line has to be injected from a secret at install time. The pattern: read the password from a secret, base64-encode username:password, append it to the project's .npmrc (which is fine — the file is regenerated per job and never pushed):

- name: Authenticate to the registry
  env:
    MODULARITYJS_NPM_TOKEN: ${{ secrets.MODULARITYJS_NPM_TOKEN }}
  run: |
    AUTH=$(printf '%s' "ci-user:${MODULARITYJS_NPM_TOKEN}" | base64 -w0)
    echo "//npm.modularityjs.com/:_auth=${AUTH}" >> .npmrc

- run: pnpm install --frozen-lockfile

Use a dedicated read-only CI user, not a developer account.

Coding agents (Claude Code, Cursor, MCP, …)

Agents that spawn pnpm dlx or npx @modularityjs/... outside the project root do not read the project-level .npmrc — they pick up only ~/.npmrc. For agent-driven workflows (the MCP server, regenerating AGENTS.md, running pnpm create @modularityjs to scaffold a new app), the scope mapping and the _auth line both need to be in ~/.npmrc:

@modularityjs:registry=https://npm.modularityjs.com/
//npm.modularityjs.com/:_auth=<base64(username:password)>

This is the only case where the scope mapping has to be duplicated in the home file.

Troubleshooting

• ERR_PNPM_FETCH_404 or package not found — the scope mapping is missing or pointing at the wrong registry. Check .npmrc for the @modularityjs:registry=... line.
• 401 Unauthorized on install — auth is missing or stale. Re-run npm login (or refresh the _auth line in ~/.npmrc).
• Works locally but CI fails — the secret isn't being injected, or the username: prefix is wrong. Double-check the printf line includes both username and :.
• Agent / pnpm dlx fails but in-repo install works — credentials are project-local. Move them to ~/.npmrc.