Thanks for your interest in contributing to the flixlix-cards monorepo! This repository contains multiple Home Assistant cards.
Tip
The same guide with nicer formatting (and screenshots) lives at cards.flixlix.com/contributing.
- Node.js (LTS recommended): Download
- pnpm: Install Instructions
- Docker (for the local Home Assistant via
pnpm hass:upand for the visual tests viapnpm test:visual): Get Started
Each card is located in its own folder inside packages/flixlix-cards:
power-flow-card-plushome-flow-cardenergy-flow-card-plusenergy-breakdown-cardsortable-list-cardenergy-period-selector-plus
Shared logic, components and types live in packages/shared.
Each package contains its source code, changelogs, and relevant scripts.
-
Install all dependencies at the root of the monorepo:
pnpm install
-
Select a card to work on. Change to the desired package directory, e.g.:
cd packages/flixlix-cards/power-flow-card-plus -
(Optional) Start Home Assistant locally (from the repo root, needs Docker):
pnpm hass:up
This builds the cards, starts Home Assistant at http://localhost:8123 (user
dev, passworddev) with dummy entities and one dashboard per card already loading the built cards. Seee2e/README.md. Alternatively, use your own Home Assistant instance. -
Rebuild on change: run
pnpm devin the card's package folder and reload the browser. With your own instance, addhttp://<your-ip>:5001/<card-filename>.jsas a dashboard resource instead. -
Run the end-to-end tests against that instance with
pnpm e2e. -
Stop it with
pnpm hass:down(pnpm hass:resetwipes its state). -
Make your code changes. Follow
CODING_STANDARDS.md, then run the checks below before committing.
The repo uses Vite+ (vp): Oxfmt for formatting, Oxlint (type-aware) for linting and Vitest for tests. Configuration lives in the root vite.config.ts; repo-specific lint rules live in packages/tooling/lint-rules.
pnpm check # format check + lint + type errors (tsgolint)
pnpm format # apply formatting
pnpm typecheck # tsc per package; optional, pnpm check already reports type errors
pnpm test # Vitest per package: node tests, then browser tests in ChromiumCI runs the same commands except pnpm typecheck; a pull request must pass all of them with zero lint errors.
The Vite+ docs ship locally at node_modules/vite-plus/docs.
Each card has <card>.browser.test.ts files next to its source that mount the card in a real Chromium (Vitest browser mode with Playwright) against a fake Home Assistant: fakeHass, mountCard and the shared flowScenarios table live in packages/shared/src/testing. Install Chromium once:
pnpm --filter power-flow-card-plus exec playwright install chromium<card>.visual.browser.test.ts files compare screenshots. Fonts render differently per OS, so they run only inside the pinned Playwright Docker image:
pnpm test:visual # compare against the committed baselines
pnpm test:visual:update # rewrite the baselines after an intended visual changeFailed comparisons leave the actual and diff images in packages/flixlix-cards/<card>/.vitest/attachments/. When bumping playwright in pnpm-workspace.yaml, bump the image tag in .github/workflows/test.yaml and regenerate the baselines.
This monorepo uses Changesets to manage version bumps and release notes across all packages.
-
If your changes affect a released card, run:
pnpm changeset
Follow the prompts to create a changeset. Pick
patchas the bump, also for new options and features: the cards are still on 0.x, whereminoris kept for very large features (on the scale of multiple batteries) and nothing getsmajorbefore 1.0. When in doubt, choosepatchand say so in the PR. Then write its summary for someone using the card: one paragraph of at most 280 characters, starting with its type. The type picks the section of the release notes:Type Section breaking:⚠️ Breaking changesfeat:✨ New fix:🐛 Fixes perf:⚡ Performance docs:📖 Docs chore:🧰 Maintenance --- "home-flow-card": patch --- feat: the battery's label can show its state of charge before, after or above its power with `battery.state_of_charge_position`.
Say what changed for the user; leave the how, examples and tables to the README and docs.
pnpm checkand the pre-commit hook reject a changeset without a type, with more than one paragraph or over 280 characters.pnpm installsets up the hook; if your global git config setscore.hooksPath, point this repository at it once withgit config core.hooksPath .vite-hooks/_ && pnpm exec vp hooks enable. -
Release notes and versioning are handled automatically. Each card's GitHub release groups its changesets by type and ends with the support links and a link to the full changelog (
packages/tooling/release-notes).
If you have questions, get stuck, or need clarification:
- Check the card’s own README for usage details or quirks.
- Feel free to create an issue on GitHub describing your problem or question.
This project is released under the MIT License.