Project

How to contribute

Thanks for your interest in improving flixlix-cards! This guide walks you through setting up the monorepo, working on a card, and getting your changes merged.

MonorepopnpmChangesets
Open the repo Report an issue

1. Prerequisites

Node.js
LTS recommended
Download
pnpm
Package manager
Install
Docker
Optional, for dev Home Assistant instance
Get started

2. Repository layout

flixlix-cards is a Turborepo + pnpm monorepo. Each card is its own package in packages/flixlix-cards. The docs site you're reading right now lives in apps/web.

text
flixlix-cards/
├─ apps/
│  └─ web/                      # this docs site
├─ packages/
│  ├─ flixlix-cards/
│  │  ├─ power-flow-card-plus/
│  │  ├─ energy-flow-card-plus/
│  │  └─ energy-breakdown-card/
│  ├─ shared/                   # shared utilities & i18n
│  ├─ ui/                       # shadcn-style UI primitives
│  ├─ utils/                    # tiny helpers (cn)
│  └─ tooling/                  # eslint, prettier, tsconfig presets
├─ pnpm-workspace.yaml
└─ turbo.json

3. Local setup

Fork the repo on GitHub, clone your fork, and install dependencies once at the root.

bash
git clone https://github.com/<your-username>/flixlix-cards.git
cd flixlix-cards
pnpm install

4. Working on a card

Move into the package you want to change and start the dev build. Most card packages ship a dev script that watches the source and rebuilds the bundle.

bash
cd packages/flixlix-cards/power-flow-card-plus
pnpm dev
Local Home Assistant
To test the card end-to-end, you need a Home Assistant instance. From the repo root you can spin one up via Docker:
pnpm start:hass
Then open http://localhost:8123 and add the local resource http://<your-ip>:5001/<card-filename>.js to your dashboard.

5. Working on the docs site

The site you are reading is in apps/web. Run it locally with:

bash
cd apps/web
pnpm dev

Routes live in src/routes. The docs use TanStack Router's file-based routing, adding a new file under src/routes/_docs/ automatically appears on the site.

6. Code quality checks

Before pushing, run the same checks CI runs.

bash
pnpm format:check   # prettier
pnpm lint           # eslint
pnpm typecheck      # tsc --noEmit
pnpm test           # vitest
Note
Each package also has a precommit script that runs the relevant subset.

7. Add a changeset

We use Changesets to manage versions and generate release notes for the published cards.

If your change affects a released card, run:

bash
pnpm changeset

Pick the affected packages, pick the bump type (patch, minor, or major) and write a clear summary. The summary appears in the next release notes.

8. Commit, push, open a PR

  1. Create a feature branch: git checkout -b feat/your-feature.
  2. Commit using a clear message, we use Conventional Commits style (feat:, fix:, chore:, etc.).
  3. Push your branch and open a pull request against main.
  4. Mention any relevant GitHub issues. Screenshots / GIFs help a lot for UI changes.
bash
git checkout -b feat/grid-color-toggle
git add .
git commit -m "feat(power-flow): add color toggle for grid icon"
git push -u origin feat/grid-color-toggle

9. Review & release

A maintainer will review your PR, request changes if needed, and merge once it's ready. Releases are automated by the changesets bot, once your changeset is merged into main, a release PR is opened that bumps versions and publishes new artifacts to HACS / GitHub.

Need ideas?

Triage issues
Reproduce bug reports and confirm whether they still happen on the latest version.
Tackle a TODO
Each card has a to-do list in its README, improvements, new options, more language support.
New card
Build a new card on top of the shared utilities, open an issue first to coordinate.

License

flixlix-cards is released under the MIT License. You are free to use, fork, modify, and redistribute the cards, including through HACS.

Thanks!

Every contribution, code, docs, bug reports, or sharing the project, keeps this monorepo alive. Thank you.

Open pull requests Branches← Back to docs home