Skip to content
pkgPlease Docs

Getting Started

pkgPlease sits in front of npm as a registry proxy: every install goes through https://npm.pkgpls.com instead of https://registry.npmjs.org directly, so pkgPlease can score packages and enforce your org’s policy before a tarball reaches disk.

The dashboard (https://app.pkgplease.com) and the registry proxy (https://npm.pkgpls.com) are deliberately on separate domains — the dashboard’s WAF and bot protection would otherwise interfere with npm/pnpm’s non-browser requests.

1. Issue a token

Section titled “1. Issue a token”

Go to Settings → Service Tokens and issue a new token with scope “Registry only” (the recommended default — it can install packages but not call the management API). Copy the token; it’s shown once.

See Registry & Tokens for the other token types (developer, agent, provisioner) and when to use each.

2. Configure your npm client

Section titled “2. Configure your npm client”

Add these two lines to your .npmrc (project-level or ~/.npmrc):

registry=https://npm.pkgpls.com/
//npm.pkgpls.com/:_authToken=${PKGPLEASE_TOKEN}

Set PKGPLEASE_TOKEN as an environment variable rather than writing the raw token into the file — npm expands ${VAR} syntax in .npmrc at install time, so the token never touches a file that might get committed.

pnpm does not expand ${VAR} syntax from a project-level .npmrc — put this in your user-level ~/.npmrc instead if you use pnpm, or substitute the literal token.

3. Restricted-network CI

Section titled “3. Restricted-network CI”

If your CI runner has an egress allowlist, add npm.pkgpls.com to it — installs will otherwise fail to resolve the registry host.

Next steps

Section titled “Next steps”