npm
Scopes routed to the hub, short-lived credentials, publishing npm packages
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
--scopefor several scopes. --default-registrymakes the hub npm's default registry for every package, instead of routing scopes.--npmrcnames 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;
--forcereplaces 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:
- uses your login to get a token that works only for that registry;
- hands it to npm in a temporary configuration file that only you can read, and removes the file when npm exits;
- adds
--ignore-scripts=true, so no package's install scripts run while a credential is available; - 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 withENEEDAUTH. Unset it forgritpack 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 searchandgritpack infolist native packages and crates only. To look at an npm package, usenpm viewthrough 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 installoutside the bridge follows your own npm settings, as it always has.
What just happened
- One line in
.npmrcsent your scope to the hub; npm's public registry stayed the default for everything else. gritpack npm rungave npm a credential for minutes, for one registry, with install scripts off, and left nothing behind.gritpack publishpacked 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 publishruns for you, including several packages released together.