home-assistant/frontend: the web client behind Home Assistant, and how to build it

What home-assistant/frontend actually is, and who it is for

This is the web client that Home Assistant serves to browsers. The README describes it as "the official Home Assistant frontend" and points at a live demo at demo.home-assistant.io. It is not a library you import into an unrelated app, and it is not the Home Assistant server: the Python backend lives in a separate repository, and this one talks to it.

The audience is narrow and specific. Card and panel authors who need the real component set rather than the published bundle. Contributors fixing UI bugs or adding dashboard features. People running a fork because they want a different look or an extra panel. If your goal is to automate a home, you never touch this repository; you install Home Assistant and use the interface it ships.

The topics list names the technology honestly: lit-element, polymer, webcomponents, TypeScript. Lit is the current component model, and Polymer appears in the topic list as history. Anyone expecting React or Vue should stop here, because the component idiom is custom elements and declarative templates, not JSX.

How the frontend is put together: build scripts, suites and the dev server

The repository is organised around suites rather than one monolithic bundle. Top-level entries include src/, demo/, gallery/, cast/, landing-page/ and build-scripts/. The package.json scripts confirm the split: dev runs the app suite, dev:demo runs the demo suite, dev:gallery runs the gallery suite, and test:e2e passes all three names to test/e2e/run-suites.mjs.

That structure matters when you debug. The gallery is where individual components are rendered in isolation, which is the fastest way to see a card or a dialog without booting a whole Home Assistant instance. The demo suite is the environment behind demo.home-assistant.io, where the UI runs against fixture data instead of a live server. The app suite is the real client.

The build itself goes through build-scripts/build-manager.mjs, and bundling uses rspack.config.cjs. Linting is split into four separate jobs: eslint, prettier, types via the TypeScript native binary, and lit-analyzer for template type checking. The lint script chains all four, and eslint runs with --max-warnings=0, so a warning fails the run. Tests run under vitest with a dedicated config at test/vitest.config.ts, and there is a separate benchmark config.

One consequence of the suite layout is that a change can pass in the gallery and still break the app, because the gallery mounts components with its own context. Treat the e2e runner as the integration gate, not the unit tests.

Installing the frontend and running it for the first time

The README gives a short path. Initial setup is script/setup, and the README points to developers.home-assistant.io for the full development guide. Node version is pinned by .nvmrc, so check that before installing; the repository uses Yarn with a committed .yarn directory and .yarnrc.yml.

Run the setup script from the repository root. It prepares the environment, and the package.json postinstall hook installs husky, so git hooks are configured as part of the install.

script/setup

After setup, start the app suite. The dev script passes --suite app to build-scripts/dev-server.mjs, which serves the frontend for development.

yarn dev

If you want the interface without connecting to your own Home Assistant instance, use the demo suite instead. The README lists the same entry point under a different name, and package.json maps it to demo/script/develop_demo.

yarn dev:demo

For component work, the gallery is the tighter loop. The README documents it as cd gallery && script/develop_gallery, and package.json exposes the same thing as yarn dev:gallery.

yarn dev:gallery

A production build is a single command, and it runs the build manager rather than a bare bundler call.

yarn build

To check that your checkout is healthy before you change anything, run the test suite. It uses vitest with the config in test/vitest.config.ts.

yarn test

Where the frontend is the wrong tool

The biggest limitation is coupling. This codebase speaks the Home Assistant websocket API and depends on Home Assistant's own state and entity model. There is no documented path in the README for pointing it at a different backend, and the demo suite works by substituting fixtures, not by abstracting the API. If you want a general dashboard builder, you would be fighting the data layer the whole way.

The licence is the second thing to check. The README says Home Assistant is "open-source and Apache 2 licensed", and pyproject.toml declares license = "Apache-2.0" with license-files = ["LICENSE*"]. The repository metadata, however, reports NOASSERTION, which means the platform could not map the licence file to a known identifier. That is a metadata gap rather than a contradiction, but it is worth reading LICENSE.md yourself before you reuse code.

The third limitation is cost of entry. A full checkout pulls a large dependency tree, four separate lint jobs, browser-based end-to-end suites and a build manager. For someone who wants to change one card's styling, the gallery is enough; for someone who wants a small standalone widget, cloning this repository is the wrong starting point entirely.

Finally, the README itself is thin. It delegates development detail to an external site and does not document rollback, release branching or how a version in pyproject.toml (20260826.0) relates to the tags in the release list (20260826.7). Those are questions the README is silent on.

Alternatives, and the real difference in approach

The most honest alternative is not another framework but the published frontend bundle. Home Assistant ships a built frontend as part of the server, so if you only need the interface, you install Home Assistant and never build anything from this repository. The difference is that you get a fixed version with no source-level control, while this repository gives you the source and the toolchain at the cost of a full build environment.

A second alternative is writing cards against the documented custom card interface rather than forking the frontend. A card is a web component registered with Home Assistant; it does not require the frontend repository at all, only the card API. Forking the frontend means you now track upstream changes to the dashboard, the entity model and the build scripts, which is a permanent maintenance commitment.

A third is a general-purpose web component library such as Lit itself, which this project uses. Lit gives you the component model without the Home Assistant data layer. The trade-off is that you then write your own state handling, your own entity registry and your own connection to the backend, which is precisely the work this repository has already done.

Maintenance, releases and upgrade cost

The repository is not archived, and the last push was on 2026-09-22, the same day as this assessment, so it is under current development. The release list shows a steady cadence: 20260826.4 on 2026-09-02, 20260826.6 on 2026-09-04, and 20260826.7 on 2026-09-11. The version scheme is date-based, which makes it easy to see how far behind a fork has fallen.

Upgrade cost depends on how deep your changes go. If you only add a card or a panel and register it through the supported extension points, upstream releases are mostly a rebase. If you modify src/ directly, every release is a merge against a fast-moving TypeScript and Lit codebase, and the four lint jobs will surface API changes for you, which is helpful but also means a broken build after every pull.

The toolchain is another recurring cost. Node is pinned by .nvmrc, Yarn is pinned by .yarnrc.yml and the committed .yarn directory, and the build runs through rspack. Upgrading any of those is a project in itself, and the presence of renovate.json suggests dependency updates arrive as automated pull requests rather than as a quiet background process.

On licensing, the README's statement and pyproject.toml both point at Apache 2.0, while the repository metadata says NOASSERTION. If you plan to redistribute a modified frontend, read LICENSE.md and the CLA.md file in the repository root before you rely on either statement. This is not legal advice; it is a pointer to the files that govern reuse.

Editorial conclusion

Adopt this repository if you are writing Home Assistant cards, custom panels or a fork of the dashboard, or if you want to send a fix upstream. Do not adopt it if you need a standalone web framework or a general-purpose design system: it is bound to the Home Assistant websocket API and to its own state model. Verify first that your Node version matches .nvmrc, that yarn install completes with the postinstall husky hook, and that yarn test passes on your machine before you change anything.

Frequently asked questions

Official sources

1. home-assistant/frontend on GitHub
2. Issues
3. Project website
4. README
5. Releases