Use npm with Pier

Pier’s registry tracks the npm registry HTTP spec end-to-end, so every npm release from 7 through 11 works against it without bespoke flags.

Configure

.npmrc in your project root (or ~/.npmrc for a global default):

registry=https://YOUR-PIER-HOST/registry/npm/
//YOUR-PIER-HOST/registry/npm/:_authToken=pier_npm_…
always-auth=true

always-auth=true is harmless on npm 7+ and required for yarn 1 — keep it so the .npmrc works for both clients.

Install

# Public package — proxied from npmjs.org if upstream proxy is on
npm install left-pad

# Private package
npm install @your-org/internal-lib

# Specific dist-tag
npm install @your-org/internal-lib@beta

Publish

# package.json carries the version
npm publish

# Or pin the target without touching .npmrc
npm publish --registry=https://YOUR-PIER-HOST/registry/npm/

Login (browser flow)

npm login --auth-type=web --registry=https://YOUR-PIER-HOST/registry/npm/
# → opens browser, authenticate in Pier panel (with 2FA)
# → pier_npm_… token written to .npmrc automatically

The legacy npm login (without --auth-type=web) uses the CouchDB user creation flow — also supported. The web flow inherits 2FA from the panel; the CouchDB flow does not prompt for OTP. If you require 2FA on every token mint, disable CouchDB login in panel settings.

Dist-tags

npm dist-tag add @your-org/[email protected] beta
npm dist-tag ls @your-org/lib
npm dist-tag rm @your-org/lib beta

Deprecate

npm deprecate @your-org/[email protected] "use 1.2.x"
npm deprecate @your-org/[email protected] ""   # un-deprecate

Unpublish

npm unpublish @your-org/[email protected]
npm unpublish @your-org/lib --force    # whole package

Versions matrix

npm version	Status	Notes
7	✓	Works out of the box
8	✓	Works out of the box
9	✓	Works out of the box
10	✓	Works out of the box
11	✓	always-auth config warning is harmless

Common errors

• 401 Unauthorized on install — token missing or always-auth=true absent from .npmrc. See Troubleshooting.
• 409 Conflict on publish — version already exists. Bump in package.json.
• npm warn Unknown project config "always-auth" on npm 11 — flag is deprecated but still honored. You can ignore the warning.

Related

• Setup — initial configuration walkthrough.
• Publish — full publish workflow.
• CI integration — npm in GitHub Actions and GitLab CI.