chadtmiller.com/npm-sample
A sample npm package, published from this repository with npm publish
npm-sample
A sample npm package, @chadtmiller/greet, published from this repository
with plain npm publish to the npm registry knotless serves for it. The
steps below are the ones that published it, so you can do the same from a
repository of your own.
Install it
Point the package's scope at this repository's registry, in your project's
.npmrc:
@chadtmiller:registry=https://knotless.dev/npm/did:plc:bcgltzqazw5tb6k2g3ttenbj/3n2sbrzrwk7pg/
Then install it as any package:
npm install @chadtmiller/greet
node -e "console.log(require('@chadtmiller/greet').greet('you'))"
# Hello, you, from knotless!
Reading the registry needs no login. Every other scope still comes from npm's own registry.
Publish your own
Each public knotless repository has its own npm registry, at
https://knotless.dev/npm/<your DID>/<repository key>/. A version
published there is a release of the repository, kept in your atproto
account, and shown on its Releases tab with these install lines.
1. Make a repository and push your package
knotless repo create knotless://<handle>/<name> --description "..."
git init -b main
git add -A && git commit -m "My package"
git push knotless://<handle>/<name> main
Give the package a scoped name in package.json, such as
@<scope>/<package>. The scope is how npm knows to fetch it from this
registry and everything else from npm's.
2. Find the registry's address
The address uses your DID and the repository's key, which never change, unlike a handle or a repository's name. The repository's record says both:
curl -s "https://knotless.dev/xrpc/dev.knotless.getRepo?repo=at://<handle>/dev.knotless.repo/<name>" \
| jq -r '"https://knotless.dev/npm/\(.uri | split("/")[2])/\(.key)/"'
For this repository that prints
https://knotless.dev/npm/did:plc:bcgltzqazw5tb6k2g3ttenbj/3n2sbrzrwk7pg/.
Check it answers with npm ping --registry <address>.
3. Point your scope at it
In the package's .npmrc, or your own ~/.npmrc:
@<scope>:registry=<address>
4. Log in with an app password
Make an app password for your account at your PDS (in Bluesky: Settings, then Privacy and security, then App passwords). Then:
npm login --registry <address>
npm finds no web login and asks for a username and password instead: give
your handle and the app password. npm whoami --registry <address>
should then print your handle. Only the repository's owner can publish to
its registry.
npm keeps the token, <handle>:<app password>, in ~/.npmrc. You can
write it there yourself instead of running npm login, for example in CI:
//knotless.dev/npm/<your DID>/<repository key>/:_authToken=<handle>:<app password>
5. Publish
npm publish
That's all. The version shows on the repository's Releases tab, and
npm install @<scope>/<package> works for anyone with the
@<scope>:registry= line.
What to know
- A version never changes. Publishing a version a second time is
refused, and
npm unpublishis refused too, so a lockfile that pins a version can always install it. - Withdraw a version with
npm deprecate. It yanks the version: it is no longerlatest, but anyone who pinned it can still install it.npm deprecate <package>@<version> ""takes the yank back. The message you give isn't kept: a yanked version readsyanked by its owner. latestis worked out, not tagged. It is the highest version that is not a pre-release and not yanked. npm asks for a tag to publish a pre-release (npm publish --tag next), but the tag isn't kept, andnpm dist-tag addis refused.- Use a scoped name. An unscoped package can be published, but installing it means sending every unscoped name to this registry, so install it by its tarball URL instead (the Releases tab shows it).
- Public repositories only.
npm publish --provenanceisn't supported.