WTH Why is building custom cards so hard?

tl;dr; We’re lacking docs, typescript types, and helpers to create custom UI components. It’s hard to create a new project with custom cards. I’d love to see a better DX for building new cards.

I’m a software engineer with 11 years of experience building frontends, typically React, but I’m happy with anything. After years of using home assistant and wanting to contribute to the community with some more bespoke cards (mushroom is great, but it’s purposefully not including oddly specific things that a lot of other cards do) all configurable by the UI. Basically a spot for Minimalist lovers to evolve towards, but modernize it a bit.

Wow this turned out to be a lot harder than I was expecting…

  • There is basically no documentation, fine I can read mushrooms source code
  • There is little in the way of typescript types, fine I can lift that from mushroom’s source and home assistant’s source
  • Docs and building the UI elements for customizing from the UI is worse. I got a lot of milage looking at mushroom’s source again, attempting to lift typescript types for the custom components out of home assistant’s source code and reusing the existing form as much as possible… but then struggling to jam new components for things that it doesn’t do all without docs or types.

Phew! I gave up. I got really close, I have a project that uses React 19 (Which supports webcomponents) creating custom react cards using emotion’s CSS in JS, and barely got some amount of customization in the UI working but I spent too many hours to not get far enough and the future doesn’t look much brighter. I expect I’d reach a point where I’d built enough infrastructure to interface with what HA is expecting that it wouldn’t be a chore, but it’s still quite the chore.

I would love to see some packages published that have helper functions, types, docs, for creating custom cards. Home assistant is too big of a project for there to be so little FE customization that’s truely easy to use and setup. I’d like to see more folks get involved and building more cool things we can all use, but it’s sooo hard right now. WTH!

For context, here’s the project I started, it attempts to port the Minimalist area card so it can be configurable in the UI: GitHub - barlock/ha-bento

Did you see

I went through the same when I experimented with custom cards. Yes, some examples and docs exist out there, but I wish there was something more official. Something where we don’t need to duplicate code, whether it’s copied from core or a template repo.

For example: window.loadCardHelpers() has some helpful methods. But I haven’t found any package which provides just the types required to use it. Or those of LovelaceCard and LovelaceCardConfig. Or even HomeAssistant itself.

I extracted all types from the frontend repo and added an index.d.ts to re-export those which I needed:

But obviously, it would be great if the declarations were split off into a package which would be used by the frontend. It wouldn’t be necessary for each and every type, just for the ones which are interesting for frontend devs.

On a similar note, I think every “extension” has to bundle its own copy of Lit, right? I realize this is due to the way TypeScript compiles, but I was wondering if there’s a way to reuse more.