chadtmiller.com/npm-sample
A sample npm package, published from this repository with npm publish
0
0
# 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/<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
```sh
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:
```sh
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`:
```ini
@<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:
```sh
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:
```ini
//knotless.dev/npm/<your DID>/<repository key>/:_authToken=<handle>:<app password>
```
### 5. Publish
```sh
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.