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

chadtmiller.com/npm-sample

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

0
0
main
117 lines · 3.9 KB Raw History
# 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.