Add on Development

Add-on Development

The Home Assistant add-on lives in addon/ and the root repository.yaml registers the add-on repository.

Files

File	Purpose
addon/config.yaml	Add-on manifest: name, version, slug, Ingress (ingress_port: 3000), panel_title: Glance, optional port.
addon/build.yaml	Per-arch base images (ghcr.io/hassio-addons/base:stable) + OCI labels.
addon/Dockerfile	Multi-stage: stage 1 clones the public repo + npm run build; stage 2 runs vite preview (which also serves the /layout persistence API).
addon/run.sh	bashio startup: seeds layouts.template.json → /data/layouts.json on first run, exports LAYOUT_FILE + PORT, runs vite preview.
addon/layouts.template.json	Generic starter layout seeded on first run.
addon/icon.png / addon/logo-glance.png	Store art. SVG sources: icon.svg, logo.svg.
addon/README.md / addon/CHANGELOG.md	Add-on docs.
repository.yaml	Registers the repo as an add-on repository.

Versioning (keep in sync!)

• package.json version and addon/config.yaml version must match (currently 0.9.3.1-beta).
• Bump addon/config.yaml on every add-on change so HA detects an update and re-registers the sidebar panel. Add a matching addon/CHANGELOG.md entry.

Gotchas

• ARG BUILD_FROM must be declared in the global scope (before the first FROM) or the build fails with "base name (${BUILD_FROM}) should not be blank."
• The sidebar panel title only re-registers when the add-on (re)starts — a config change alone won't update a cached panel name. Restart the add-on (or toggle "Show in sidebar" off/on).
• First install builds from source on-device — it needs internet and takes a few minutes.
• Update reliably rebuilds from latest source. The Dockerfile ADDs the GitHub API commit endpoint for DASHBOARD_REF right before git clone, so the clone layer's cache is busted whenever main moves. Without it, an Update could reuse a cached (stale) clone and ship old code — only the Rebuild button (--no-cache) would have been reliable.
• Generating art: use rsvg-convert (e.g. rsvg-convert -w 600 logo.svg -o logo-glance.png). ImageMagick's SVG path is unreliable here (no Ghostscript).
• The logo filename includes a suffix (logo-glance.png) to bust GitHub's image cache after updates.

Release checklist

1. Make the change in src/ (or addon/).
2. npm run build → must be 0 errors.
3. Bump version in both package.json and addon/config.yaml.
4. Add an addon/CHANGELOG.md entry.
5. Update docs and this wiki for anything user/dev-facing.
6. Commit + push to main.