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):

@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:

$ 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:

<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.