# 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`: ```ini @chadtmiller:registry=https://knotless.dev/npm/did:plc:bcgltzqazw5tb6k2g3ttenbj/3n2sbrzrwk7pg/ ``` Then install it as any package: ```sh 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///`. 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 ```sh knotless repo create knotless:/// --description "..." git init -b main git add -A && git commit -m "My package" git push knotless:/// main ``` Give the package a scoped name in `package.json`, such as `@/`. 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: ```sh curl -s "https://knotless.dev/xrpc/dev.knotless.getRepo?repo=at:///dev.knotless.repo/" \ | 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
`. ### 3. Point your scope at it In the package's `.npmrc`, or your own `~/.npmrc`: ```ini @:registry=
``` ### 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: ```sh npm login --registry
``` npm finds no web login and asks for a username and password instead: give your handle and the app password. `npm whoami --registry
` should then print your handle. Only the repository's owner can publish to its registry. npm keeps the token, `:`, in `~/.npmrc`. You can write it there yourself instead of running `npm login`, for example in CI: ```ini //knotless.dev/npm///:_authToken=: ``` ### 5. Publish ```sh npm publish ``` That's all. The version shows on the repository's Releases tab, and `npm install @/` works for anyone with the `@: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 @ ""` 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.