Decide whether to publish Hyperaudio Lite on npm

[maboa]

Context

Hyperaudio Lite is currently distributed via this repo — users either vendor the file directly, link to it on GitHub Pages, or load it from a CDN that mirrors the repo. There is no hyperaudio-lite package on npm under the project's control.

#218 raised the question of how the library should be distributed (ESM vs CJS vs classic script). Going further than that and publishing on npm is a related but separable decision worth thinking through on its own.

Why it might be worth doing

• Discoverability. Lands the library in npm install and search results, which is where most modern frontend devs look first.
• Reproducible install. Consumers pin a version, get lockfile entries, get Dependabot alerts when a known-vulnerable version exists.
• Cleaner downstream integration. Editor and other Hyperaudio projects could just declare a dependency instead of vendoring.
• Forces good hygiene. Versioning, changelogs, and release process become explicit rather than implicit.

Why to think twice

• Maintenance pressure rises. Every release becomes a semver promise. Quiet periods that are fine for a vendored project read as "abandoned" on npm. Users assume timely security patches.

• Supply-chain target. Small-maintainer libraries are a known npm attack vector (event-stream, ua-parser-js, and many since). Becoming a published package puts the project in the trust chain of every consumer — including ones who only wanted a <script> tag. Requires 2FA, ideally provenance signing, ideally CI-only publish tokens.

• Scanner / Dependabot noise. Already an issue for this repo because of jest's transitive deps. Publishing multiplies that — downstream scanners also see the manifest, and you'll get bug reports about vulns you can't directly control.

• Expectation creep. TypeScript definitions, source maps, tree-shakable ESM, CI badges, semver discipline, deprecation cycles. The "single 800-line file" ethos gets steady pressure to formalize tooling. Resisting it is doable but ongoing work.

• Ecosystem mismatch. npm is Node-flavored. A pure browser library will get Node-shaped bug reports (SSR, tree-shaking, module resolution edge cases) that have nothing to do with what the library actually does.

• Operational overhead. npm org (@hyperaudio scope), publish tokens, CI automation, possibly a prepublishOnly build, trademark considerations on the name. npm unpublish has tight time windows — a bad release at midnight is painful.

• De-emphasizes "vendoring is the docs." Currently the install instructions are essentially "copy the file." Publishing risks making that a second-class story unless deliberately maintained.

Possible decision framework

Probably worth asking:

1. Is anyone actually waiting on this? If downstream projects (Hyperaudio Lite Editor etc.) currently vendor or git-submodule the file and would prefer a real dependency, that's a strong pull.
2. Who is willing to be the publisher? Single maintainer with 2FA + provenance + automation? Or a small group? This determines bus factor.
3. What scope? hyperaudio-lite (unscoped, more discoverable, more naming risk) or @hyperaudio/lite (scoped, safer, signals "this belongs to the project").
4. What release cadence is realistic? If the honest answer is "every 6-12 months", publishing under explicit "pin a version, expect quiet periods" framing in the README would set expectations correctly.

Middle paths

• Don't publish, just keep vendoring + improve the <script> story. Resolve Distribute the library in ESM and CJS forms in addition to the classic script #218 (ESM/CJS sibling files), keep distribution as "grab the file." Lowest cost, no new responsibilities. Probably best fit if no one is actively asking for the npm package.

• Publish but explicitly low-tempo. Push the package with README framing like "small project, please pin versions, security patches are best-effort." Accepts the cost but manages expectations.

• Publish under a Hyperaudio Foundation / org account. Spreads maintainer load across multiple people; more resilient against bus-factor and account-compromise risk. Requires the org to exist as more than one person.

Related

• Distribute the library in ESM and CJS forms in addition to the classic script #218 — distribution format (ESM/CJS) is a prerequisite for any decent npm release
• Replace positional-boolean constructor signature with an options object #217 — options-object constructor would make the published API less embarrassing to lock in

Recommendation (mine, easily redirectable)

Lean toward don't publish for now. The current pull doesn't seem strong, the maintenance cost is real, and the supply-chain target consideration matters more for small-maintainer libraries than people generally admit. If/when a downstream project specifically wants the dependency form, revisit then under a scoped (@hyperaudio/lite) name with clear cadence framing.