Homeassistant configuration structure

I’ve been working on my Homeassistant config for quite a while now, so I would like to share my folder structure.

I’ve seen quite a lot of examples out there, and I tried to collect the best ideas of all of them, leveraging scalability of the tree of configurations and keeing it simple when I need to search for something there.

I’ll show you my structure and then I’ll give you some examples of the configs.

Folders 🗂

Here’s an output of a tree -d call on my /hass-config folder:

.
├── automations
├── binary_sensors
├── custom_components
├── includes
│   ├── lovelace
│   └── packages
├── scenes
├── sensors
│   └── templates
├── switches
└── www

📂 `automations`

Inside the automations folder, I keep a single file for each automation.

This is easier for SCM, and you’ll go exactly to the right file when you open the folder:

automations
├── fontdoor.yaml
├── newupdate.yaml
├── sunroom_movement.yaml
└── ...

Where, i.e., newupdate.yaml contains a single automation entry:

- id: "home_assistant_update"
  initial_state: True
  trigger:
    platform: state
    entity_id: updater.updater
  action:
    - data:
        message: "New HomeAssistant Update available"
      service: telegram_bot.send_message

So, there are a lot of automation files, but how do we join them all? Quite easy, actually.

Your configuration.yaml file must contain the following:

automation: !include_dir_merge_list automations

This means that: every file contained inside automations folder, will be treated as an element of an array, so the contents of each file must contain a valid automation node.

The same process applies for binary_sensors, switches, scenes folders.

📂 `www`

On this folder, I save my custom components, to use in Lovelace UI.

Things like:

`custom_components` 📂

In order to have my custom UI components up2date with their source code, I have my custom_updater script on this folder. As per docs, it “allows you to track and update custom cards or components and python scripts”.

Really handy 👌

📂 `includes/lovelace`

In order to have my Lovelace UI configuration organized + keeping it scalable, I keep this folder as a source to feed my ui-lovelace.yaml, following this structure:

├── main.yaml
├── ...
├── lights.yaml
├── configuration.yaml

As main.yaml represents the root of the configuration, each yaml file is a tab on my Lovelace UI.

Here you can see how I call all these separate files, on my ui-lovelace.yaml file:

title: Home
resources:
  - url: /local/mini-graph-card-bundle.js # Here is a custom UI component
    type: module
  - url: /local/mini-media-player-bundle.js # Here is another custom UI component
    type: module
views:
  - !include includes/lovelace/main.yaml # These are the files for
  - !include includes/lovelace/lights.yaml
  ...
  - !include includes/lovelace/configuration.yaml

Wrap up

There are a lot of config organizations you can use, but the best is the one that fits your needs.

So gather some ideas, read a lot of github user shared configurations, and you’ll eventually get your stuff organized too.

Most definitely you’ll learn some new cool automations that you didn’t know they were possible ✨.

It’s a process, not an immediate task.

I’ll be sharing my config soon, it’s it the process of being prepared to be open-source. ⏳

Sources 📚

For more information on the best practices of splitting your massive configuration.yaml, check the following links:

Homeassistant: Splitting up the configuration
User shared homeassistant configs @ Github
Awesome Homeassistant
You can also read some good posts on reddit @ r/homeassistant.

Folders 🗂

📂 automations

📂 www

custom_components 📂