~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/npm-sample

A sample npm package, published from this repository with npm publish

0
0
main
Go to filet
Code
README.md

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 unpublish is 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 longer latest, 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 reads yanked by its owner.
  • latest is 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, and npm dist-tag add is 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 --provenance isn't supported.