# ha-fusion: a Svelte dashboard for Home Assistant, and what its maintenance status means for you > ha-fusion is a custom Home Assistant dashboard built with SvelteKit and shipped as a Supervisor add-on or a Docker container on port 5050. The upstream README now says the repository is no longer actively maintained and points to a fork, so the decision is as much about which codebase you install as about the dashboard itself. **matt8707/ha-fusion** — A modern, easy-to-use and performant custom Home Assistant dashboard - Repository: https://github.com/matt8707/ha-fusion - Stars: 3,016 · Forks: 175 - Language: Svelte - License: MIT - Published: 2026-09-24 · Updated: 2026-09-24 · Language: en - Canonical page: https://hysenlabs.com/projects/matt8707-ha-fusion ## What ha-fusion replaces, and who it is aimed at Home Assistant ships a dashboard editor, but complex layouts end up as YAML you edit by hand and reload to see. ha-fusion is a separate dashboard application that talks to your Home Assistant instance over its HTTP API and gives you a visual editing surface instead. The README describes it as a modern, easy-to-use and performant custom dashboard, and the project is written in Svelte, which is what the Svelte and SvelteKit entries in package.json reflect. The intended user is someone who has Home Assistant running already and wants a wall-mounted or tablet-facing view they can rearrange without touching configuration files. The keyboard shortcuts table is a good signal of that audience: f filters, esc exits, cmd+s saves, cmd+z undoes, cmd+shift+z redoes. Those are editor shortcuts, not end-user shortcuts. If you are happy with a handful of Lovelace cards, this project is more machinery than you need. ## How ha-fusion is put together: SvelteKit, Node, and a data directory The repository is a SvelteKit application built with Vite and served by a Node process. The Dockerfile shows the shape clearly: a first stage based on node:22 runs npm install, npm run build and npm prune --omit=dev; a second stage based on node:22-alpine copies only build, node_modules, server.js and package.json. The container then sets PORT=5050, NODE_ENV=production and ADDON=false and starts with node server.js. That split matters for two reasons. First, the runtime image carries no build toolchain, so you cannot rebuild the frontend inside a running container. Second, the application expects a writable /app/data volume, which is where docker-compose.yml mounts /path/to/ha-fusion. Your dashboard configuration lives there, not in the image, so container replacement does not wipe it as long as the volume path is correct. The frontend stack is visible in package.json: CodeMirror 6 packages for the editor surface, d3-array, d3-scale and d3-shape for charting, @iconify/svelte for icons, and @event-calendar packages for calendar views. Home Assistant connectivity is configured through environment variables rather than through the Home Assistant frontend itself, which is why the project can run as a standalone container. ## Installing ha-fusion as a Supervisor add-on or with Docker There are two supported paths, and the README ties each to an installation method. For Home Assistant OS or Supervised, add the add-on repository at https://github.com/matt8707/addon-ha-fusion to your instance, refresh the add-on store, and install ha-fusion from the list. There is no command line step for this route. For Container or Core installations, the README points at the repository's docker-compose.yml, which you edit and place in a directory of your choosing. The shipped file uses the image ghcr.io/matt8707/ha-fusion, maps port 5050, mounts /path/to/ha-fusion into /app/data, and sets two environment variables. ```yaml services: ha-fusion: container_name: ha-fusion image: ghcr.io/matt8707/ha-fusion volumes: - /path/to/ha-fusion:/app/data network_mode: bridge ports: - 5050:5050 environment: TZ: Europe/Stockholm HASS_URL: http://192.168.1.241:8123 restart: always ``` Replace the volume path with a real directory on your host, set TZ to your timezone, and point HASS_URL at your Home Assistant address. Then start the container from the directory holding the compose file: ```bash cd path/to/docker-compose.yml docker-compose up -d ha-fusion ``` After that, open http://your-host:5050 and the dashboard should load. If it does not, the README names the two places to look: the Log tab when running as an add-on, or docker logs ha-fusion for a Docker setup, plus the browser console for frontend errors. Updating is two commands, and the order matters because the running container is only replaced on the second one: ```bash docker-compose pull ha-fusion docker-compose up -d ha-fusion ``` If you run without compose, the README states that each update requires stopping the container, removing it, pulling the new image, and running docker run again. The equivalent single-container invocation it gives is: ```bash docker run -d \ --name ha-fusion \ --network bridge \ -p 5050:5050 \ -v /path/to/ha-fusion:/app/data \ -e TZ=Europe/Stockholm \ -e HASS_URL=http://192.168.1.241:8123 \ --restart always \ ghcr.io/matt8707/ha-fusion ``` A Kubernetes chart also exists under charts/ha-fusion, and the README links to its own README rather than documenting values inline. ## Query strings, Ingress, and the wall-tablet case Two URL parameters are documented, and they only work when you have exposed a port, either through the add-on configuration or through Docker. The README states plainly that when using Ingress, query strings cannot be read. That is a real constraint if you installed through the add-on in its default ingress mode and then wondered why your parameters did nothing. Appending ?view=Bedroom loads the view named Bedroom when the page opens. Appending ?menu=false disables the menu button, which the README frames as a way to prevent unwanted dashboard changes on wall-mounted tablets. Both are useful for a kiosk setup where you want the browser to land on a fixed screen and stay there. Neither is a security control: hiding the menu button does not restrict who can reach the port, so if the container is exposed beyond your LAN, the menu is one URL parameter away from coming back. ## The maintenance question the README answers itself The most consequential paragraph in the README is the one headed Important. It states that the repository is no longer actively maintained and that development continues in a maintained fork, knowald/ha-fusion, described there as Svelte 5 with ongoing fixes and new features. The matching add-on repository is knowald/addon-ha-fusion, and the fork's README carries a short migration guide. This is unusual in a good way: the upstream project tells you where to go instead of leaving you to discover it. But it also means the version numbers in this repository stop at 2024.10.1, released on 2024-10-11, and the package.json still declares version 2024.10.0 with Svelte 4.2.19. The last push to the repository was on 2026-07-07, so there has been activity after the final release, but the README's own statement about maintenance is the thing to weigh, not the push timestamp. The practical consequence is that bug reports and feature requests against matt8707/ha-fusion have no upstream owner. If you install from the add-on repository URL in this README, you get the unmaintained line; if you want fixes, you install from the fork instead. The migration guide is where the compatibility details live, and this README does not reproduce them. ## Where ha-fusion is the wrong tool, and what to use instead The honest alternative is Home Assistant's own Lovelace dashboard. It has no separate container, no port to expose, no HASS_URL to configure, and it upgrades with Home Assistant itself. Its editor is weaker for dense, visually arranged layouts, and anything beyond the card set means YAML, which is exactly the friction ha-fusion removes. So the difference in approach is architectural, not cosmetic. Lovelace renders inside the Home Assistant frontend and shares its session and ingress model. ha-fusion is a standalone SvelteKit application that authenticates against the Home Assistant API and stores its own layout in /app/data. That buys you the visual editor and the query-string view targeting, and it costs you a second service to run, a port to expose, and a data directory to back up. There are cases where ha-fusion is simply wrong. If your Home Assistant runs in a way that cannot expose port 5050, the query-string features are unavailable and you are running a container for a dashboard Home Assistant could have served. If you have one screen and a dozen entities, the setup overhead is not repaid. And if you need a dashboard that tracks Home Assistant's own frontend releases without a third party in between, the built-in option is the safer default. ## Licence, upgrades, and what a fork means for both The repository is MIT licensed. That is permissive: it allows use, modification and redistribution provided the copyright notice and permission notice are kept, and it is the reason a fork like knowald/ha-fusion can exist and be distributed at all. It also means nobody is obligated to maintain anything. MIT gives you rights, not a support contract, and the README's Important section is the project exercising that freedom. For upgrade cost, the Docker path is the cheaper one: docker-compose pull ha-fusion followed by docker-compose up -d ha-fusion, with state preserved in the mounted volume. The add-on path defers to the Supervisor's own update mechanism. The non-compose path is the expensive one, since the README describes a stop, remove, pull, run cycle for every update. Moving to the fork is not a drop-in image swap as far as this README is concerned, because it does not describe the procedure. It says the fork's README has a short migration guide, and that is where the steps are. Treat the migration as a separate task with its own backup of /app/data, not as part of a routine pull. ## Conclusion Adopt ha-fusion if you run Home Assistant OS or Supervised and want a visual, drag-and-drop dashboard instead of hand-written YAML, and you are willing to track the fork the README points at. Do not adopt it if you need an actively maintained upstream, if you cannot expose a port (Ingress breaks the view and menu query strings), or if you only want a few simple cards, where the built-in Lovelace UI is less machinery. Before committing, verify which repository you are installing from, that port 5050 is free or remapped, and that HASS_URL points at your instance. ## FAQ ### How do I install ha-fusion? On Home Assistant OS or Supervised, add the add-on repository at https://github.com/matt8707/addon-ha-fusion, refresh the add-on store, and install ha-fusion from the list. On Container or Core, use the repository's docker-compose.yml with the ghcr.io/matt8707/ha-fusion image, set HASS_URL and TZ, and run docker-compose up -d ha-fusion. ### How do I use ha-fusion to open a specific view? Append the view query string to the URL, for example ?view=Bedroom, and that view loads when the page opens. The README notes that query strings only work if you have exposed a port, and that they cannot be read when using Ingress. ### Is ha-fusion still maintained? The README states that the repository is no longer actively maintained and that development continues in the fork knowald/ha-fusion, with knowald/addon-ha-fusion as the matching add-on repository. The last release listed here is 2024.10.1 from 2024-10-11. ### How do I update a ha-fusion Docker container? The README gives two commands: docker-compose pull ha-fusion, then docker-compose up -d ha-fusion. Without compose, it says each update requires stopping the container, removing it, pulling the new image, and running docker run again. ### Where does ha-fusion keep its dashboard configuration? The compose file mounts a host directory into /app/data, which is the writable path the container uses. Replacing the container leaves that data intact as long as the volume mapping points at the same host directory. ### How do I debug ha-fusion when the dashboard does not load? The README points to the Log tab when running as an add-on, or to docker logs ha-fusion for Docker setups. For frontend problems it says to open the browser console. ## Sources - [Issues](https://github.com/matt8707/ha-fusion/issues) - [License: MIT](https://github.com/matt8707/ha-fusion/blob/main/LICENSE) - [matt8707/ha-fusion on GitHub](https://github.com/matt8707/ha-fusion) - [README](https://github.com/matt8707/ha-fusion/blob/main/README.md) - [Releases](https://github.com/matt8707/ha-fusion/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/matt8707-ha-fusion