Open-source project
home-assistant/frontend avatar
home-assistant/frontend

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

:lollipop: Frontend for Home Assistant

5,804 stars3,971 forksTypeScriptApache-2.0

At a glance

What is it?
The repository holds the official Home Assistant web interface, a TypeScript and Lit codebase with its own build scripts, gallery and demo suites. This is a guide to what it does, how to run it locally, and where it stops being the right thing to fork.
Who is it for?
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.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • home-assistant/frontend5,804 ★ · +131
Star history
Repository2026-09-232026-11-15
home-assistant/frontend5.7k5.8k

131 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

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 codebase is TypeScript, and its lint script runs lit-analyzer over the src/ templates. 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 dev script confirms the split: it passes --suite app to build-scripts/dev-server.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.

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 contributors.home-assistant.io/frontend/development/ for the full development guide. Node version is pinned by .nvmrc, so check that before installing; the repository uses pnpm, with pnpm-lock.yaml and pnpm-workspace.yaml at the root.

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.

bash
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.

bash
pnpm run dev

For component work, the gallery is the tighter loop. The README documents it as cd gallery && script/develop_gallery.

bash
cd gallery && script/develop_gallery

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

bash
pnpm 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.

bash
pnpm run 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. 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 also reports Apache-2.0, 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 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 (20261028.0) relates to the tags in the release list (20261028.3). 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-11-01, so it is under current development. The release list shows a steady cadence: 20261028.1 on 2026-10-29, 20261028.2 on 2026-10-30, and 20261028.3 on 2026-11-02. 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, dependencies are locked in pnpm-lock.yaml, 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, pyproject.toml and the repository metadata all point at Apache 2.0. 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 pnpm install completes with the postinstall husky hook, and that pnpm run test passes on your machine before you change anything.

Frequently asked questions

What is home-assistant/frontend?

It is the repository for the official Home Assistant frontend, the web client that Home Assistant serves to browsers. The README links to a live demo at demo.home-assistant.io and describes the project as the official frontend.

How do I install home-assistant/frontend for development?

The README lists script/setup as the initial setup step and points to contributors.home-assistant.io/frontend/development/ for the full development instructions. The Node version is pinned in .nvmrc, and the postinstall hook in package.json installs husky.

How do I run home-assistant/frontend locally?

package.json defines a dev script that runs the app suite through build-scripts/dev-server.mjs. The README documents the gallery separately as cd gallery && script/develop_gallery.

What licence does home-assistant/frontend use?

The README states that Home Assistant is open-source and Apache 2 licensed, and pyproject.toml declares license = "Apache-2.0" with license-files = ["LICENSE*"]. The repository metadata also reports Apache-2.0; read LICENSE.md directly if reuse matters to you.

Can I use home-assistant/frontend with a backend other than Home Assistant?

The README does not document any way to point the frontend at a different backend.

Official sources

  1. home-assistant/frontend on GitHub
  2. Issues
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/home-assistant-frontend.svg)](https://hysenlabs.com/projects/home-assistant-frontend)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/home-assistant-frontend.svg)](https://hysenlabs.com/projects/home-assistant-frontend)

Was this useful?