docs

bus-docs

The source of the consumer docs at https://node-ts.github.io/bus, built with VitePress. This file is for people writing the docs; it isn't published. How to run and deploy the site is in the Docs section of CONTRIBUTING.md.

pnpm build             # the packages, which the snippets and API reference are built from
pnpm docs:dev          # http://localhost:5173/bus/, reloading as you edit
pnpm docs:typecheck    # type check every snippet against the built packages
pnpm docs:build        # build to docs/.vitepress/dist; fails on dead links
pnpm docs:check-redirects
pnpm docs:sync-readmes # write the package READMEs' code blocks from snippets/
pnpm docs:check-readmes

Layout

Path	What's there
index.md	The landing page (layout: home)
getting-started/, guide/	Pages, one markdown file each. A page with children, such as guide/workflows.md, sits next to its folder
transports/, persistence/	Adapter pages, with transports.md and persistence.md as their overviews
upgrading/v2.md	Renders the repo's MIGRATING.md, which stays the single source
api/	Generated by typedoc from each package's root exports at build time. Not committed; don't edit it
snippets/	Every TypeScript snippet the pages show
public/	Files served as they are: brand assets and diagrams
.vitepress/config.mts	Navigation, sidebars, search, llms.txt and the head tags
.vitepress/theme/	The custom theme: brand styles in style.css, and the components below
redirects.json	Old paths and the pages they moved to. The build writes a redirect stub at each (.vitepress/redirect-stubs.ts)
scripts/	The redirect check and the old sites' paths it checks against, and the README sync
typedoc.json, typedoc/	The API reference config, and a plugin that fails the build on a {@link} that doesn't resolve

A new page needs an entry in the sidebar in .vitepress/config.mts, in the section it belongs to: Getting started, Guide, Transports, Persistence or Reference.

Page template

Every page follows the same shape. guide/messages/events.md is a good one to copy.

---
title: Events
description: One sentence for search results, social cards and llms.txt.
---

# Events

One paragraph: what the page covers and when you'd use it.

## A section

The content, with snippets from docs/snippets.

<<< @/snippets/events.ts#publish

## See also

- [Commands](/guide/messages/commands)
- [`handlerFor`](/api/bus-core/functions/handlerFor) in the API reference

Frontmatter:

• title (required): the page's title, as in the sidebar.
• description (required): one sentence, used for the meta description, social cards and llms.txt.
• outline (optional): the heading levels in "On this page", such as [2, 2]. The default is [2, 3].
• next / prev (optional): only on the last or first page of a section, to link across sections.

Write in plain, short sentences. Link to other pages with root-relative paths without .md, such as /guide/workflows, and to the API reference for the details of a type. The build fails on a link to a page that doesn't exist.

Snippets

Every TypeScript code block comes from a file in snippets/, so that pnpm docs:typecheck checks it compiles against the packages. Don't write TypeScript inline in a page. Shell commands, JSON and other languages can stay inline.

• Write snippets the way an app would: import from the package roots, and import messages from snippets/messages. snippets/services and the *-client.ts/*-store.ts files are stand-ins that pages don't show.
• Show a whole file with <<< @/snippets/file.ts, or part of one with <<< @/snippets/file.ts#region, marking the part with // #region name and // #endregion name. Add [Label] after it to title it in a code group.
• A bus that receives messages needs .withMessageTypes(messageTypes). After adding or changing a message or workflow state in snippets/, run pnpm --filter bus-docs run generate:message-types and commit snippets/message-types.generated.ts.
• Snippets are linted and formatted like the rest of the repo.

Package READMEs

Each package's README.md is published to npm with it, and is the first thing people see there. It's short, and links to the site for everything else. Every package README has the same shape:

# @node-ts/<package>

One or two sentences: what it is, and which part of @node-ts/bus it fills.

[![npm](https://img.shields.io/npm/v/@node-ts/<package>)](https://www.npmjs.com/package/@node-ts/<package>)

**[Documentation](https://node-ts.github.io/bus/<its page>)** · [Changelog](https://github.com/node-ts/bus/blob/master/packages/<package>/CHANGELOG.md)

## Installation

Requires Node.js 24 or later.

```sh
npm i @node-ts/<package> <its required peers, such as @node-ts/bus-core>
```

## Usage

The smallest complete example, from snippets/: imports, configuration, build(), initialize() and start().

<!-- <<< @/snippets/<file>.ts#<region> -->

```ts

```

## Configuration

Adapters only: an Option | Default | Description table that matches the configuration interface's JSDoc and @default values.

## Learn more

- Two to four links to the pages of the site that cover it

• Use absolute URLs, since npm doesn't resolve relative links, and link to the latest docs, at https://node-ts.github.io/bus/<page>.
• Don't add a Development section: CONTRIBUTING.md covers working on the library. Don't add support or community links either.
• Keep short warnings that people need before they first use the package, such as setting persistentMessages: true in production. Behaviour and deep dives go on the site.
• Every TypeScript code block comes from snippets/. Put a <!-- <<< @/snippets/file.ts#region --> marker before it, in the same form as a page's <<<, and run pnpm docs:sync-readmes to write the block. pnpm docs:check-readmes, which CircleCI's docs job runs after the build, fails if a block is out of date or has no marker, if a link to the site, its headings or a file in the repository doesn't resolve, or if a package README doesn't follow this shape.

Components

Pages may use these components, registered globally in .vitepress/theme/index.ts, and no others. Leave a blank line inside a component around markdown content.

Component	Use it for
<FeatureGrid> with <Card title link tag> inside	Section overviews and the landing page: a grid of linked cards
<Steps> around an ordered list	A procedure, such as installing something. Start each item with a bold title
<PackageBadge pkg="bus-sqs" />	The top of an adapter page: the package name, its npm version and its source
<Diagram src alt caption />	A committed SVG from public/diagrams/. alt describes what it shows
::: code-group	Tabs: npm, pnpm and yarn commands, or the function and class versions of a snippet
::: tip, ::: info, ::: warning	Callouts

Diagrams are hand-written SVG with a white background and the brand colours, so they read in light and dark mode.

Brand

The logo (public/logo.svg, also favicon.svg), the social card (public/og.svg, rendered to og.png) and the teal accent (--bus-* in .vitepress/theme/style.css) are placeholders, made to be easy to replace. To rebrand, replace the SVGs, re-render og.png from og.svg (the command is in the file), and change the colours in style.css.