Skip to content

Fix missing README on npm; modernize package documentation; add maintainer docs #605

@oberstet

Description

@oberstet

Context

AutobahnJS 26.3.1 was just published with strict-mode fixes for Vite 8 / Rolldown. A full-stack demo (Vue 3.6 + Pinia 3 + Vite 8 + Crossbar.io) with Vitest and Playwright tests now exists. The README should reflect this modernized state.

Problem

The npm package page currently shows:

"This package does not have a README. Add a README to your package so that users know how to get started."

This is because packages/autobahn/package.json has a files field that only includes index.js and /lib, and there is no README.md inside packages/autobahn/. npm publishes from that directory, so the repo root README.md never makes it into the tarball.

Root cause

"files": [
  "index.js",
  "/lib"
]

No README.md in packages/autobahn/, and README.md is not listed in files.

Fix

Option A (simplest): Add "README.md" to the files array and either symlink or copy the repo root README into packages/autobahn/.

Option B (better): Create a dedicated packages/autobahn/README.md tailored for npm consumers (install, quick start, link to full docs), since the repo root README contains developer/contributor info that isn't relevant to npm users.

I'd recommend Option B — the npm README should be focused and concise:

  1. One-liner: what it is (WAMP for browsers and Node.js)
  2. Install: npm install autobahn
  3. Quick start example (connect, subscribe, call — 20 lines)
  4. Key features (RPC, PubSub, cryptosign auth, browser + Node.js)
  5. Compatibility: Node.js 22+, modern browsers, Vite 8 / Rolldown
  6. Links: full docs, GitHub repo, Crossbar.io, WAMP spec
  7. License

Additional README improvements

The repo root & npm README should contain direct links to the release version on both:

  • the Git tagged version on GitHub, e.g. v26.3.1
  • the corresponding npm published version, e.g. v26.3.1

The repo root README.md could also use updates:

  • Remove outdated references (autobahn-browser, autobahn-xbr, XBR Network links) — XBR is no longer actively developed
  • Add Vite 8 / Rolldown bundling guidance (the stub plugin for msgpack5/cbor/when, global: 'globalThis', use_es6_promises: true)
  • Add WAMP-cryptosign browser example (using tweetnacl)
  • Reference the full-stack demo: blueprints/vue-autobahnjs
  • Update the "Platform Requirements" to mention Vite/Rolldown compatibility
  • Update code examples to use ES module imports (import autobahn from 'autobahn') alongside the existing CommonJS example

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions