flowbun-registry

The package registry for flowbun. Each package bundles one or more flowbun blocks, optionally with example wiring (flows), ready to be installed into a flowbun instance's data/ directory from the editor's package manager.

Layout

index.json                          generated — never edit by hand
packages/
  <package-name>/
    <version>/                      immutable once published
      flowbun.json                  package manifest
      README.md                     human-facing description
      blocks/*.ts                   block files, installed to data/blocks/
      blocks/__tests__/*.test.ts    optional bun tests
      wiring/*.json                 optional example flows, installed to data/wiring/
scripts/build-index.ts              regenerates index.json

Versions are plain folders, not git tags: published versions are immutable, old versions stay fetchable forever, and installers only ever need raw-file HTTPS (raw.githubusercontent.com/<owner>/flowbun-registry/main/packages/<name>/<version>/<file>) — no git, no tarballs. To change a package, add a new version folder.

The manifest (flowbun.json)

{
  "name": "outdoor-temp",
  "version": "1.0.0",
  "description": "Poll Open-Meteo for the current outdoor temperature",
  "author": "aquarat",
  "flowbun": ">=0",
  "npmDependencies": { "zod": "^4.1.0" },
  "blocks": ["blocks/outdoor_temp.ts"],
  "wiring": ["wiring/outdoor_temp_demo.json"],
  "tests": []
}

• name — kebab-case, must match the package folder name.
• version — major.minor.patch, must match the version folder name.
• flowbun — semver range of compatible flowbun versions.
• npmDependencies — npm packages the blocks import. The installer runs bun add for these into the instance's data/package.json before copying files, so block imports resolve at runtime and in the typecheck gate.
• blocks — every file under blocks/, relative to the version folder, install target data/blocks/ (preserving subpaths, so blocks/__tests__/foo.test.ts lands at data/blocks/__tests__/foo.test.ts).
• wiring — every file under wiring/, install target data/wiring/.
• tests — informational only: the subset of blocks that are test files. Not a separate install target; test files are already covered by blocks. Lets the index (and the editor's package browser) flag which packages ship test coverage without a separate fetch pass.

Every file in the folder except flowbun.json and README.md must appear in blocks or wiring (the index build enforces this, so an installer that fetches only listed files can never miss one).

Conventions the index build enforces

• Wiring ships disabled. Every wiring file must carry a top-level "disabled": true. An installed flow that auto-started would immediately act on the user's Home Assistant; the user reviews the flow, points its nodes at their own entities, and enables it in the editor.
• Block filenames are globally unique across packages. flowbun installs blocks flat into data/blocks/ and a block's name must equal its filename, so two packages shipping debounce.ts could never be installed together. Pick distinctive names.
• No secrets or personal identifiers. Wiring configs and block defaults must use generic placeholder entity IDs (sensor.grid_power, cover.living_room_blinds), never real device IDs, account numbers, or home coordinates.

index.json

index.json is the only file installers fetch to browse the registry: every package, every version, its manifest fields, and a sha256: hash for each file (verified by the installer after download). It is deterministic output — regenerate it with:

bun scripts/build-index.ts          # rewrite index.json
bun scripts/build-index.ts --check  # exit 1 if index.json is stale (CI)

Publishing a package

1. Create packages/<name>/<version>/ with flowbun.json, a README.md, and your files.
2. Run bun scripts/build-index.ts (it validates the package and rewrites index.json).
3. Open a PR. CI re-runs the build in --check mode and fails if the index is stale or any validation rule is broken.

Note that installing a flowbun package means running its code with access to the user's Home Assistant — review submissions accordingly.