npm repositories work with npm, pnpm, Yarn and Bun, and answer every npm command that talks to a registry. Hosted repositories take npm publish; proxy repositories cache the npm public registry or a mirror.
1. Sign in
Sign in once per computer with npm login --registry <the repository's address>: it opens Depotex in your browser, you approve it, and npm saves an API token. Or put an API token in .npmrc yourself:
registry=https://depotex.example.com/repository/my-space/npmjs/
@acme:registry=https://depotex.example.com/repository/my-space/js/
//depotex.example.com/repository/my-space/js/:_authToken=${DEPOTEX_TOKEN}
//depotex.example.com/repository/my-space/npmjs/:_authToken=${DEPOTEX_TOKEN}This uses a proxy repository of the public registry by default and a hosted repository for your @acme scope, so private packages are never looked up publicly. pnpm, Yarn (npmRegistryServer and npmScopes in .yarnrc.yml) and Bun (bunfig.toml) read the same addresses.
Or use one address for everything: with an npm group as the space's default, registry=https://depotex.example.com/repository/my-space/npm/ installs from your hosted repositories and the public registry, and npm publish goes to the repository the group's write rules choose. One _authToken line for that address covers every package.
2. Commands
| Command | What happens |
|---|---|
| install, ci, update, outdated, exec/npx, view | Packages come from the repository; a proxy fetches from its upstream and links tarballs to itself. |
| publish | Hosted repositories, Publish permission. A version can't be overwritten (lockfiles pin its checksum); the tarball is checked against the checksums npm sends. --provenance attestations are kept and served. |
| unpublish | A version, or the whole package with --force; Delete permission. |
| deprecate, dist-tag, owner | Overwrite permission. |
| star, stars | Anyone who can download. |
| search | Names, descriptions and keywords (keywords: and scope: work too); a proxy asks its upstream. |
| audit | The upstream's advisories, plus versions the block list blocks (critical) and quarantined versions (high). |
| whoami, ping, profile get, token list/revoke, logout | As usual; logout revokes the token. |
| access get status, access list packages | Answered from the space's visibility and your permissions. |
A few commands are for what npmjs.com manages itself: npm token create, password sign-in (--auth-type=legacy), profile set, two-factor, team, org, hook and changing access. Depotex refuses them and says where to do it instead: API tokens under Profile, sign-in with npm login, space members and repository access, groups, and automation rules.
3. Versions and policies
- Each package version is a version in Depotex: cleanup, quotas, quarantine and the block list apply to it.
- Blocked versions are left out of package documents, and dist-tags move to the newest version left.
- With Hide quarantined versions, quarantined versions are left out too; otherwise they're listed and their tarballs refused with the reason.
4. Proxy repositories
Add an upstream with the npm public registry preset (https://registry.npmjs.org) or your mirror, allow it for the space, then create a proxy repository. Package documents are re-checked after the metadata age; tarballs are fetched on first request and kept.
5. In the artifact browser
Packages show by scope, then name. The Overview shows the description, license, homepage, repository, author, dist-tags, keywords, engines, entry points and a deprecation warning; the README tab shows the package's README (no HTML or remote images); Dependencies lists runtime, peer, optional and dev dependencies; provenance shows under Security.
6. Limits
- One registry address serves one repository: combine hosted and proxied packages with scope registries until group repositories come.
- Depotex doesn't sign packages, so npm audit signatures reports the registry as unsupported. Provenance from npm publish --provenance is kept and served.
- Tokens from npm login carry your repository permissions for everything you can reach, not one repository. Create a narrower API token for CI.
- Proxies expect the standard name/-/file.tgz tarball layout.
- A proxy that hides quarantined versions knows only quarantines of versions it has cached.
- Depotex link upstreams aren't available for npm yet.