Splitting config best practice

I have always struggled with splitting my configuration.yaml file up, and have honestly only ever got things working by persistently trying different methods until one works…i.e. !include_dir_list, !include_dir_named , !include_dir_merge_list, !include_dir_merge_named.

what is generally considered to be best practice?
I think at the moment I have a (too much so) random mix of methodology and approach.
So for example, in my .homeassistant folder I have the configuration.yaml in the root, which may reference !include recorder.yaml, but then I have a folder structure for other things for example: ~/.homeassistant/media-player and inside here I have google.yaml and kodi.yaml etc

I think I may have confused myself more by making my folder organisation poorly, so I am looking to fully overhaul, but want to make sure I do it as best as possible…starting with understanding fully the splitting of configs.

And yes, I’ve read the docs, but I think I need it explaining to me like I’m an 10.

This is my split

And some of my config.yaml



I don’t think there is a ‘best practice’, just what works best for you in your config, and how your brain works when you’re tinkering.

For me I’ve found using packages is the best.

1 Like

I have yet to dive down that path.

I am working on trying to get all my automations into Node Red

Ha, and I’m yet to experiment with node-red, but intend to at some point :grinning:

My setup is all on my GitHub if you want to see a fully package based config in action…

link removed

1 Like

I am curious to know the pros and cons of this configuration style. I guess it prevents having to call out the same entity_id in multiple areas? like a customize and a group could be combined?

For me it’s that when I’m tinkering with something all of the bits that make it up are in the same file.

So if you have an input_number.yaml and an input_select.yaml and an automation.yaml and you have an alarm clock on your front end that uses elements from each, and you want to add a new automation for your alarm clock, you either have to have a really good memory to remember what the various parts are called or have 3 files open and keep flicking between them.

Whereas with packages you’d have an alarm_clock.yaml with all the parts in, so at most you have to scroll up, but realistically auto-complete already knows the entity_id you want.

Also makes sharing config a bit easier, because people can just copy the file rather than a bit from here and there.

But yeah, as you say, combining the bits has multiple advantages for me.

1 Like

Some interesting points. Thanks guys.

I’m still struggling to understand the different approaches and their pros and cons. (!include_dir_merge_named xxx for example)

1 Like

I ran into this last night, but since I am trying to move all my automations to nodered, I don’t have to worry about creating automations with packages. Perhaps I will look into it one day.

For instance, I have one for my ‘groups’. The contents of one of these files called ‘doors.yaml’ inside this directory consists of the following:

  name: Garage Doors
    - cover.garage_door

  name: Entry Doors
    - sensor.frontdoor
    - sensor.backdoor
    - sensor.garageentry
    - sensor.sidedoor

  name: Doors
  icon: mdi:garage
  view: yes
    - group.garagedoors
    # - group.door_sensors
    - group.entry_doors
1 Like

I would recommend keep monolithic config and breaking up only when you it is hard to find stuff.

I only split out each of the customisation/automation/groups/scripts into individual files.

Automations is getting kind of large so I will likely move that into an automations directory and start splitting that into smaller parts.

Eventually I will likely move to also include the package concept for certain isolated components.

1 Like

I thought it was messy as soon as I started adding components. By the time I had 6 switches with customizations, I decided it was time to split. As someone who likes to split up their code into libraries and specific functional packages, I find one large config file very ugly.

I found that the components I worked on the most were the grouping and automations, there rest of quite static. For these, they are typically a mash of different inputs and outputs so I plan to then seperate these based on function (I have a bunch of perimeter alerts, have light automations, etc).