bee-js Documentation Website

Documentation for the Swarm Bee-js javascript library. View at bee-js.ethswarm.org.

Node Version

You must use node 18 or above. We recommend nvm.

Installation

$ npm i

Local Development

$ npm start

This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.

Build

$ npm run build

This command generates static content into the build directory and can be served using any static contents hosting service.

Bumping Version

Don't forget to find and replace the version number for the whole of the docs folder.

API Reference (docs/api)

Everything under docs/api is typedoc output generated from the bee-js sources and committed to this repository, so the site builds without a bee-js checkout.

Regenerating

The generator reads two clones that are not part of this repository:

$ git clone https://github.com/ethersphere/bee-js sources/bee-js
$ git clone https://github.com/ethersphere/core-sdk sources/core-sdk
$ npm --prefix sources/bee-js install

Check both out at the release you are documenting, then run:

$ npm run generate-api

This drives typedoc via typedoc.config.mjs and reshapes the output into the layout the site expects: it lifts the main entry point's pages out of the bee-js/src directory typedoc nests them in, flattens the Utils namespace into docs/api/namespaces/Utils, folds the namespace class pages into docs/api/classes alongside the rest, turns the generated index into Overview.md, reduces references to TypeScript's own lib.*.d.ts to a machine-independent form, and links the @ethersphere/core-sdk re-exports against the core-sdk clone (scripts/fix-core-sdk-links.mjs, also runnable on its own as npm run fix-api-links).

Review the result as a diff against what is already committed. Anything unrelated to the bee-js release you are documenting means the toolchain moved, not the docs.

Things worth knowing before changing it

• typedoc and typedoc-plugin-markdown are pinned exactly. A plugin upgrade rewrites unrelated pages and drowns the diff, so upgrade them deliberately, on their own.
• The typescript devDependency exists only for this step. Nothing in this repository is TypeScript; typedoc compiles the bee-js sources with it, so it has to track what sources/bee-js requires or generation fails with type errors.
• scripts/typedoc-frontmatter-titles.mjs is not optional. typedoc escapes markdown characters in page headings (# Variable: NULL\_OWNER), and Docusaurus takes the browser tab title, sidebar label, breadcrumbs and prev/next links from that raw heading without undoing the escapes. The plugin adds an unescaped frontmatter title instead. The escaping itself is not configurable upstream, and the heading has to stay escaped or MDX parses \<V\> as JSX.
• The namespace classes reach the reference through extra entry points. The classes behind bee.data, bee.stamp and the rest live in src/modules/*.ts and are not exported from bee-js's src/index.ts, so typedoc would otherwise render them as the unlinkable type of a Bee property. typedoc.config.mjs adds src/modules/*.ts as entry points of their own to give them pages. Their names collide with exported types (Data, Tag, Pin, Collection, Chunk), which is harmless because each entry point is its own typedoc module — but it is also why nothing may fold those pages together with the exported types of the same name.
• Multiple entry points are what puts every page under bee-js/src. typedoc names a module directory after each entry point's path, so the whole reference arrives one subtree down. generate-api.mjs moves that subtree up as one piece, which is what keeps the relative links inside it correct without rewriting any of them. Should bee-js move src/modules or rename the entry file, that lift is the first thing to break.

Maintainers

See what "Maintainer" means here.

LLM-Friendly Documentation (llms.txt)

The site serves two files for AI agents at the root:

• /llms.txt — Hand-crafted index file (static/llms.txt). A curated list of every documentation page with one-line descriptions. This is the entry point AI agents use to find relevant pages.
• /llms-full.txt — Auto-generated by docusaurus-plugin-llms at build time. Contains the full text of every page concatenated into a single file.

Keeping llms.txt up to date

The validation script scripts/validate-llms-txt.mjs runs automatically during npm run build (via the prebuild hook). It cross-checks static/llms.txt against the actual doc files and prints warnings for:

• Stale links — a URL in llms.txt points to a doc page that no longer exists (renamed/deleted).
• Missing coverage — a doc file exists that isn't listed in llms.txt (new page added without updating the index).

The script is informational only (exit 0) — it won't block the build.

What to do when warnings appear

1. Stale link: Open static/llms.txt, find the flagged URL, and either update the path to match the renamed page or remove the entry if the page was deleted.
2. Missing coverage: Decide which section the new page belongs in and add a line in static/llms.txt following the existing format: - [Title](https://bee-js.ethswarm.org/docs/path): One-line description.