buuh/docs/publishing.md

# Publishing buuh on project.uhhm.no

Two different distribution problems, two different mechanisms. Gitea
handles one of them natively; the other needs a static host.

## 1. `npm install` — Gitea Packages (yes, it does what you hope)

Gitea ships a real npm registry per user/org. For the `uhhm` org the
endpoint is:

```
https://project.uhhm.no/api/packages/uhhm/npm/
```

**Publishing** happens from the release workflow
(`.gitea/workflows/release.yml`): tag `v8.0.0`, push the tag, and every
workspace package is published with a `package:write` token stored as
the `PACKAGES_TOKEN` repo secret. Bump the workspace versions before
tagging.

**Consuming** needs one line of `.npmrc` in a project (or `~/.npmrc`):

```ini
@uhhm:registry=https://project.uhhm.no/api/packages/uhhm/npm/
```

Then plain npm works, and this is why the packages are scoped: npm
routes *by scope*, so `@uhhm/*` resolves against your Gitea while
everything else still comes from npmjs.org. No token is needed to
install if the packages are public (they inherit visibility from the
owner). Starting a project is:

```console
$ echo "@uhhm:registry=https://project.uhhm.no/api/packages/uhhm/npm/" >> .npmrc
$ npm i @uhhm/buuh @uhhm/buuh-html
$ npm i -D @uhhm/bankai
$ npx bankai start app.js
```

## 2. "CDN require" — the part Gitea does NOT do

This is the misunderstanding worth clearing up: **Gitea's npm registry
serves tarballs to package managers, not individual JavaScript files to
browsers.** There is no unpkg-style `https://…/@uhhm/buuh/index.js`
endpoint, and the generic-package download URLs serve
`application/octet-stream` — browsers refuse that for ES modules (strict
MIME checking). So an import map cannot point at Gitea directly.

What works instead, in order of effort:

**a. The single-file bundle + any static host (recommended).**
`npm run bundle` produces `dist-cdn/buuh.js` — the whole framework as
one minified ES module with named exports. The release workflow uploads
it to Gitea's generic package store as the archive of record; to make it
importable, serve a copy from any host that sends
`text/javascript` + CORS. Since you run uhhm.no, that's a few lines of
Caddy:

```
cdn.uhhm.no {
  root * /srv/cdn
  file_server
  header Access-Control-Allow-Origin *
  header /buuh@* Cache-Control "public, max-age=31536000, immutable"
}
```

Drop each release in as `buuh@8.0.0.js` (a `curl` from the generic
package URL, or an extra `scp` step in the workflow), and every project
on earth can do:

```html
<script type="importmap">
  { "imports": { "buuh": "https://cdn.uhhm.no/buuh@8.0.0.js" } }
</script>
<script type="module">
  import { choo, html } from 'buuh'
</script>
```

That is the zero-build story with your own domain on it.

**b. Self-hosted esm.sh.** esm.sh is open source and can be pointed at
a custom npm registry — run it against the Gitea endpoint and you get
real CDN semantics (per-package URLs, versioning, bundling) for
everything you publish. More moving parts; worth it only if you want
per-package URLs rather than the one-file bundle.

**c. Raw Gitea file URLs — don't.** Gitea serves raw `.js` as
`text/plain` for safety, which module loading rejects. Fronting raw
URLs with a MIME-rewriting proxy works but is a hack with none of the
caching benefits of (a).

## Version hygiene

- Workspace versions are currently `8.0.0-dev`; set real versions
  before the first tag (`npm version 8.0.0 --workspaces --no-git-tag-version`).
- The tag drives the generic-package version in the workflow, so keep
  tags and package.json versions in step.
- `bankai` the bin name survives; the package is `@uhhm/bankai` so scope
  routing works.