Skip to content
Dashhaus

Repository and commands

Work on Dashhaus itself in a clone of the repository. This section names paths and commands; the rest of the site doesn’t.

The easiest help needs no clone. Dashhaus is in beta, so trying it on your own house and saying how it went is worth as much as a pull request.

Set up

Section titled “Set up”
Terminal window
git clone https://github.com/Krystosterone/dashhaus.git
cd dashhaus
npm install
npm run storybook

Node 22.23.4 or later (.nvmrc pins it; nvm install fetches it), and the npm version root package.json pins with packageManager: run corepack enable npm once, so npm in the repository is that version. Another npm stops with EBADDEVENGINES (or, older than 10.9, fails its preinstall) instead of rewriting package-lock.json. npm install links every workspace package, so the root apps read each package’s source, not a build. Storybook runs at http://localhost:6006.

Layout

Section titled “Layout”
packages/
  core/                  @dashhaus/core: entities/, ha/ (store, mappers, actions, hooks), primitives/, hooks/, demo/
  dashboard/             @dashhaus/dashboard: element, card frame, schema, layout, conformance
  deploy/                @dashhaus/deploy: the dashhaus-deploy CLI
  bundle/                @dashhaus/bundle: the prebuilt dist/dashhaus.js
  create-dashhaus-skin/  the scaffolder and the templates every skin starts from
src/skins/
  orb/                   @dashhaus/orb: cards/, shared/, bundles/, dashboards/, ha/, lovelace/, styles/
  field/                 @dashhaus/field: the same shape, without bundles
apps/lovelace/           the bundle: entry.ts (both skins' Lovelace cards in one file) and setup.ts (the setup card)
verify/                  checks across packages and skins: boundaries, conformance, Storybook, releases, docs
scripts/                 the generators (new-card, new-skin), builds, release and perf tooling
spec/                    the specification the code is held to, for maintainers and agents
docs/                    this site (Astro Starlight); its code samples are in docs/examples/

Imports go one way: an entity model imports nothing of Home Assistant, the Home Assistant layer imports no skin, a skin imports no other skin, and a skin’s cards never import the Home Assistant layer, only its ha/ and lovelace/ folders do. ESLint and verify/boundaries.test.ts hold it.

Commands

Section titled “Commands”
Command Does
npm run storybook Storybook’s dev server, every skin’s cards and dashboards on demo data
npm run check Typecheck, lint and unit tests: the gate before any change is done
npm run test-storybook Builds Storybook, then renders every story and runs axe on it in Chromium
npm run build:ha The one-file Lovelace bundle, dist/dashhaus.js, copied into packages/bundle/dist/
npm run deploy Builds the bundle and deploys the dashboards dashboard.config.mjs declares, with .env beside it
npm run docs This site’s dev server; npm run build:docs builds it with Storybook under /storybook
npm run build:packages Each public package’s dist
npm run change Writes the change note a pull request that changes what ships carries, for the next release’s notes
npm run release:check Packs the seven tarballs and installs them into a clean app
npm run new-card, npm run new-skin The generators (Add a card or a skin)
npm run perf:collect Measures the deployed dashboards in Chromium against a live Home Assistant

The commands that drive Chromium (test-storybook, perf:collect, the docs screenshots and the release journeys’ screenshots) launch the build the pinned Playwright installs (npx playwright install chromium). Where that build can’t be fetched, DASHHAUS_CHROMIUM=/path/to/chromium points them at a Chromium already on the machine.

What a change must pass

Section titled “What a change must pass”
  1. npm run check.
  2. npm run test-storybook: every story renders and passes axe, and a failure names the rule and the elements.
  3. A look in Storybook at the cards you touched: their All states, Sizes, Footprints, Compact, Worst case and Details stories, at every width.
  4. A change note, when the change reaches anyone who installs Dashhaus: npm run change -- fix "…", with breaking, feature, fix, or internal for a change no one installing it notices. Write it for someone deciding whether to upgrade. CI fails a pull request that changes what ships without one, and the next release’s notes are made of them.

CI runs the first two on every push and pull request, and packs the release to run the clean-room journeys from the tarballs alone, one for each way in but this one: installing from the Marketplace and pressing the setup card’s Create, deploying from the command line, building a skin and using the hooks, against a simulated Home Assistant. spec/journeys.md lists them, and a check fails when one loses its page or its proof.

The docs’ code samples

Section titled “The docs’ code samples”

Every code sample on this site is a file in docs/examples/, shown by docs/src/components/Example.astro. They are checked like code:

  • npm run typecheck compiles them (docs/examples/tsconfig.json) and npm run lint lints them.
  • verify/docs.test.ts fails a page with a TypeScript, JavaScript, YAML or JSON code fence of its own, parses every Lovelace YAML sample with its skin’s reader, loads the deploy config, and typechecks the author guide’s scaffold with its added domain.
  • Tests among them, such as docs/examples/testing/LightButton.test.tsx, run with the unit tests.

The API lists (options, return values, signatures) aren’t written by hand either: docs/src/lib/api.ts reads them from the packages’ TypeScript when the site builds, so a renamed option changes the page, and a removed one fails the build.