npm

Scopes routed to the hub, short-lived credentials, publishing npm packages

Chapter 11 of 34Current for Gritpack 1.2.63Source: docs/guide/11-npm.md

You work in JavaScript or TypeScript, your team has packages it keeps to itself, and you want to go on using npm install, package.json and package-lock.json the way you do now. This chapter routes your team's npm scope to the hub, so @ada/... packages come from the hub while everything else still comes from the public npm registry, and shows how to publish and install without leaving a long-lived token in any .npmrc.

Maturity: Experimental. The hub serves an npm registry that ordinary npm clients use for reading, installing, dist-tags and deprecation, and gritpack publish publishes npm packages transactionally. It is deliberately a bounded registry, not every npm service: there is no npm audit, no organisations or teams API, and no per-package access settings. Expect small changes before it is called finished.

What you will be able to do

  • route one or more npm scopes to the hub, leaving npm's public registry as the default for everything else;
  • check that npm, its routing and your login agree;
  • run npm commands against the hub with a credential that lives for minutes and is never written to your .npmrc;
  • publish an npm package to the hub, all or nothing, with a receipt.

You need a login on the hub first (Logging in).

Names you already know

npm names keep their npm meaning. An unscoped name such as left-pad is one global name on the hub; the first account to publish it owns it. A scoped name such as @ada/shout lives in the scope @ada, and only the scope's owner may publish in it. On a Gritpack hub the npm scope and the Gritpack scope are the same thing: if you own @ada (see Names, scopes and owners), you can publish @ada/shout from npm and @ada/greet as a native package.

A scope gives you the right to publish. It does not make anything private. Privacy belongs to the hub: everyone who can log in to a private hub can read every package on it, and nobody else can read any of them. For the same reason, npm's per-package restricted access is refused, and a package.json with "private": true is not published at all:

$ gritpack publish --dry-run
npm package inspection failed: invalid npm package: package.json explicitly forbids publication

1. Route your scope to the hub

In the directory of an npm package, run:

$ gritpack setup
setup adapter=npm profile=work status=changed routes=@ada config=./.npmrc
$ cat .npmrc
@ada:registry=https://packages.example.com:7446/npm/

Gritpack read package.json, saw that the package is in the scope @ada, asked the hub where its npm registry is, and added one line to the project's .npmrc. Packages in @ada now come from the hub; all others still come from npm's public registry. Running setup again reports status=unchanged.

For a project whose own name has no scope, or to route other scopes, use gritpack npm setup and say exactly what you want:

$ gritpack npm setup --registry https://packages.example.com:7446/npm --scope @ada
configured npm registry https://packages.example.com:7446/npm/ routes=@ada config=./.npmrc credentials=not-stored
  • Repeat --scope for several scopes.
  • --default-registry makes the hub npm's default registry for every package, instead of routing scopes.
  • --npmrc names another file, such as your user ~/.npmrc.
  • Setup keeps every other line of the file. If a route for the same scope already points elsewhere, it stops; --force replaces it.

credentials=not-stored is the point: the .npmrc gets routing only, never an _authToken. You can commit it.

From npm. This is ordinary npm configuration. @ada:registry=... is exactly what you would write by hand to send a scope to a private registry. The difference is where the credential comes from, which is the next section.

2. Check it

$ gritpack npm doctor --registry https://packages.example.com:7446/npm --scope @ada --profile work
healthy npm registry https://packages.example.com:7446/npm/ routes=@ada npm=11.19.0 authentication=profile:work renewable token idle_expires_at=1794900829 renew_until=1794904129

The doctor checks that npm runs, that the .npmrc routes the scope where you said, that the hub answers npm's own ping, and that a package which does not exist is reported as absent. With --profile, it uses your login to make a short-lived read token for those checks, then throws it away. Without --profile, it checks anonymous access, which is what a public hub allows.

gritpack doctor, run in the package directory, does the general checks first: your login, account and hub, then the npm routing.

3. Run npm with a short-lived credential

On a private hub, reading needs a login. Plain npm install has none, so the hub refuses it and npm suggests npm login:

npm error To correct this please try logging in again with:
npm error   npm login

Do not log in with npm. Instead, run the npm command through Gritpack:

$ gritpack npm run --registry https://packages.example.com:7446/npm --profile work -- install @ada/shout
added 1 package, and audited 2 packages in 642ms

found 0 vulnerabilities
completed npm install with renewable read credential initial_idle_expires_at=1794900862 renew_until=1794904162

Everything after -- is the npm command. Gritpack:

  1. uses your login to get a token that works only for that registry;
  2. hands it to npm in a temporary configuration file that only you can read, and removes the file when npm exits;
  3. adds --ignore-scripts=true, so no package's install scripts run while a credential is available;
  4. runs npm, and reports the token's lifetime.

The token expires after five idle minutes; each successful request extends that, up to one hour after it was made. Nothing durable is left behind.

The project then looks as it always does:

{
  "name": "app",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "@ada/shout": "^0.1.1"
  }
}
$ node -e 'console.log(require("@ada/shout").shout("hello"))'
HELLO!

and package-lock.json records the exact tarball and its sha512- integrity from the hub. Packages from other scopes in the same install still come from npm's public registry, as the .npmrc routes them.

Which npm commands Gritpack will run

To keep the credential away from code it should not reach, gritpack npm run accepts only commands that talk to the registry:

  • reading: ci, install, outdated, pack, ping, search, update, view;
  • changing: publish, dist-tag, deprecate.

Anything else is refused before npm starts:

$ gritpack npm run --registry https://packages.example.com:7446/npm --profile work -- test
invalid npm integration configuration: npm command "test" is not permitted while a registry credential is present; use a canonical registry command (ci, install, outdated, pack, ping, search, update, view, publish, dist-tag, or deprecate)

Run your scripts, tests and builds with plain npm, outside the bridge. Give the registry to Gritpack only, not to npm: a --registry after -- is refused, because the credential is made for one registry and must not travel to another.

--npm chooses which npm program to run, if npm on your PATH is not the one you want.

Careful. If your environment sets npm_config_userconfig, npm reads that file instead of the temporary one Gritpack made, finds no credential, and fails with ENEEDAUTH. Unset it for gritpack npm run.

4. Publish an npm package

Every new version needs a README of at least 100 words (npm reads README.md) and a licence: the "license" field in package.json. Then, from the package directory, check first:

$ gritpack publish --dry-run
planning publication; Cargo members may run cargo metadata/package and rustc version checks
publication plan=sha256:30a6c6b8... result=RequiresRemoteVerification nodes=1 edges=0 output=./.gritpack/publication-plan.json
npm:@ada/shout@0.1.0 adapter=Npm status=Indeterminate ...
...
  check=PUBLICATION_METADATA_INCOMPLETE status=Warning — package.json does not declare repository; catalogue pages and search will show this version without it, and a published version cannot be amended
  check=PUBLICATION_DOCUMENTATION_POLICY status=Passed — README and licence meet the hub's documentation policy
  check=PUBLICATION_LICENSE_DECLARED status=Passed — MIT
publication verification plan=sha256:30a6c6b8... repository=550e8400-e29b-41d4-a716-446655440000 result=Publishable
  npm:@ada/shout@0.1.0: New
dry run complete; registry was not mutated

Gritpack asked npm to pack the package with lifecycle scripts turned off, checked the tarball (one package/package.json at the root, regular files only, no duplicate names), kept the exact tarball, and asked the hub whether you may publish this version. Then:

$ gritpack publish
...
committed publication transaction=01a1e868-a496-7040-964b-503d44c3790e plan=sha256:085cec88... nodes=1
  npm:@ada/shout@0.1.0: New storage_id=npm-sha256:1c367eec... digest=sha256:1c367eec...

On a terminal it asks first; in scripts, add --yes. The version became visible in one step, the hub kept a signed receipt, and the tarball npm will download is byte for byte the one npm packed. --npm chooses the npm program used for packing.

Publishing with npm itself

gritpack npm run ... -- publish runs npm's own npm publish with a short-lived publishing credential. Whether the hub accepts it depends on the hub. A hub that keeps signed evidence for every publication accepts new versions only through Gritpack's transactional publication, and npm reports:

npm error code E409
npm error 409 Conflict - PUT https://packages.example.com:7446/npm/@ada%2fshout - repository evidence policy requires gritpack transactional publication

Use gritpack publish there. The bridge forces public access on npm publish, because visibility is decided by the hub, not by the package.

Deprecations and dist-tags

These work through the bridge, with npm's own commands:

$ gritpack npm run --registry https://packages.example.com:7446/npm --profile work -- deprecate @ada/shout@0.1.0 "use 0.1.1"
npm notice deprecating @ada/shout@0.1.0 with message "use 0.1.1"
completed npm deprecate with renewable publish credential initial_idle_expires_at=1794900869 renew_until=1794904169
$ gritpack npm run --registry https://packages.example.com:7446/npm --profile work -- dist-tag ls @ada/shout
latest: 0.1.1
completed npm dist-tag with renewable publish credential initial_idle_expires_at=1794900869 renew_until=1794904169

A dist-tag is a movable pointer such as latest; a version itself never changes. To fix a bad version, publish a new one.

What npm packages do not do on a hub yet

  • gritpack search and gritpack info list native packages and crates only. To look at an npm package, use npm view through the bridge.
  • There is no per-package access control, no npm organisations or teams, and no npm audit endpoint.
  • Install scripts: Gritpack never runs them, and turns them off while a credential is present. Plain npm install outside the bridge follows your own npm settings, as it always has.

What just happened

  • One line in .npmrc sent your scope to the hub; npm's public registry stayed the default for everything else.
  • gritpack npm run gave npm a credential for minutes, for one registry, with install scripts off, and left nothing behind.
  • gritpack publish packed the package with npm, checked it, and published it in one step with a receipt.

You can stop here

A JavaScript team that wanted a private scope without changing how it builds and installs is done. CI jobs need a login and the same gritpack npm run commands; see Continuous integration.

Next

  • Go modules covers the same ground for Go.
  • Optional deep dive: Publishing step by step shows the plan, verify and publish steps that gritpack publish runs for you, including several packages released together.