integration_blueprint is a starting skeleton for Home Assistant custom components, not an integration to install

The repository exists to be copied, not installed

The first line of the README is a notice, and it is the whole point of the project. The component and platforms in the repository are not meant to be used by a user, but as a blueprint that custom component developers can build upon.

The reason given is structural rather than aspirational. By having custom_components look the same in terms of README and structure, it is easier for developers to help each other and for users to start using them. That is a real argument: Home Assistant has thousands of custom integrations maintained by hobbyists, and a uniform repository shape means a bug report from one of them can be read against a known layout.

The invitation is also explicit. If you are a developer and you want to add things to this blueprint that you think more developers will have use for, open a pull request. So the repository is both a template and a shared starting point, and the pull request path is how improvements propagate to everyone who later copies it.

The repository listing confirms the Home Assistant focus. The topics are blueprint, custom-component, home-assistant and python, and the file layout includes a config/ directory, a custom_components/ directory, a hacs.json, a scripts/ directory and three requirements files, along with a .ruff.toml for lint configuration.

The file table is the specification of a good custom component repository

The README's file overview is really a checklist, and each entry links to the upstream documentation for that topic. The devcontainer config is for development and testing with Visual Studio Code, the issue templates are for the issue tracker, and CONTRIBUTING.md holds the contribution guidelines. The integration files themselves live under custom_components/integration_blueprint/, described as where everything happens, with a link to the Home Assistant developer docs on creating a component index.

The requirements split into three files, and the reasoning is the interesting part. requirements_common.txt holds packages common to CI and local development, installed first so that any pip upgrade completes before other dependencies, with a modern pip called out as an example. requirements_dev.txt holds the development and testing packages and also installs the lint tooling via requirements_lint.txt. requirements_lint.txt holds the linting packages and is installed by the Lint CI job.

That three-way split is a small piece of engineering that most hand-rolled repositories do not have, and it exists for a concrete reason: the lint job needs its tooling to be installable on its own, and the shared base needs to be installed before anything else so a pip upgrade does not get interrupted by a partially upgraded environment.

The hacs.json at the root is the metadata file for the Home Assistant Community Store, and the next steps section points at HACS documentation for publishing, which is the route by which a custom integration reaches users without being bundled with Home Assistant.

Two dependency update tools ship, and you keep exactly one

One of the more opinionated decisions in the template is that it ships with configuration for two dependency update tools, and the README tells you to pick one and remove or disable the other.

Renovate is enabled by default through .github/renovate.json. Dependabot is included but disabled, through a file named .github/_dependabot.yml, and the reason is a GitHub behaviour rather than a config trick: the leading _ prefix means GitHub ignores it. To use Dependabot instead, you rename the file back to .github/dependabot.yml and delete .github/renovate.json.

This is a small file-naming convention that carries a real amount of information, and it is a good example of the template doing work for you. A developer who copies the repository and leaves both files in place gets exactly one active updater, and a developer who wants the other one has a one line rename to do. The alternative, shipping both enabled, produces duplicate pull requests and confusion about which bot to reconfigure.

The same reasoning applies to the rest of the layout. The .devcontainer.json means the development environment is described in the repository rather than in a wiki page, so the version of Python, the installed tooling and the editor extensions are the same on every machine. The issue templates in .github/ISSUE_TEMPLATE/ mean a bug report arrives with the shape the project expects, and the custom_components/ directory follows the structure that Home Assistant itself expects at runtime, so the code you develop against the blueprint is the code that will be discovered when it is installed into a real Home Assistant configuration.

Getting started is four renames and one script

The How section is short enough to memorise, which is the point of a template. The README lists it as five numbered steps:

1. Create a new repository in GitHub, using this repository as a template by clicking the "Use this template" button in the GitHub UI.
1. Open your new repository in Visual Studio Code devcontainer (Preferably with the "`Dev Containers: Clone Repository in Named Container Volume...`" option).
1. Rename all instances of the `integration_blueprint` to `custom_components/<your_integration_domain>` (e.g. `custom_components/awesome_integration`).
1. Rename all instances of the `Integration Blueprint` to `<Your Integration Name>` (e.g. `Awesome Integration`).
1. Run the `scripts/develop` to start HA and test out your new integration.

The first step is to create a new repository on GitHub using this repository as a template, by clicking the Use this template button in the GitHub UI. The second is to open the new repository in a Visual Studio Code devcontainer, preferably with the Dev Containers: Clone Repository in Named Container Volume option, which keeps the container's state between sessions so installed packages survive a rebuild.

The third and fourth steps are the renames, and they are the part people get wrong if they skim. You rename all instances of integration_blueprint to custom_components/<your_integration_domain>, with the example given as custom_components/awesome_integration, and you rename all instances of Integration Blueprint to your own name, with the example given as Awesome Integration.

The fifth step is to run the scripts/develop script to start Home Assistant and test out the new integration. Running the development script rather than installing into your own Home Assistant is the point: the container has a Home Assistant instance with your component mounted, so a reload picks up your changes.

Note the two different namespaces being renamed. The first is the domain, which is the identifier that ends up in configuration.yaml and in the manifest, and it has to be unique across custom components. The second is the human readable name, which is what appears in the user interface. Conflating them is common when the template is copied quickly.

The next steps point at tests, branding, releases and distribution

The README closes with a short list of what to do next, and it is worth reading as the author's opinion on what a custom integration needs beyond the skeleton.

Add tests to your integration, and the README points at pytest-homeassistant-custom-component as a package that can help you get started. Add brand images, meaning a logo and an icon, which is the part users actually see in the interface. Create your first release. Share your integration on the Home Assistant Forum. And submit your integration to HACS.

The order matters slightly, because the distribution step depends on the ones before it. A repository with a manifest but no brand assets will not present properly in the UI, and a repository with no tests or no release will not be easy for a user to install and even less easy to trust.

For the tests point specifically, the mention of pytest-homeassistant-custom-component is the useful detail. Home Assistant's own test harness is designed for code running inside the core repository, and this package adapts that harness so a custom component can be tested outside it. The template ships a requirements_dev.txt, so the test dependencies are already accounted for in the layout even before you write a single test file.

The distribution step has a real dependency on HACS existing as a channel. The custom_components/awesome_integration path in the rename instructions is the same layout HACS installs into, so a repository that follows the template is already in the shape HACS expects, and the hacs.json file is the metadata that describes it.

A template with no releases, and a last push in October 2026

The repository has no GitHub releases, which is consistent with what it is. A template is versioned by the commits you copy, not by tagged artefacts, and tagging releases of someone else's starting point would be misleading.

The maintenance picture is current. The last push was on 2026-10-18, four days before this review, and the repository is not archived. The topics list includes blueprint, custom-component, home-assistant and python.

The licence is MIT, with a LICENSE file at the repository root, and the README links to the GitHub documentation on licensing a repository. Since the point of the project is that other people copy its contents into their own work, the permissive licence is what makes the copying uncomplicated, and there is no copyleft obligation on the integration you build from it. That is a licensing note rather than legal advice, and it says nothing about Home Assistant's own terms for the integrations you distribute.

The alternative to copying this template is building a repository from scratch, and the difference in approach is that a hand-rolled repository starts with a decision about every file on the list, whereas the template makes the decisions once, in a place that other developers can also improve. The cost of the template is that you inherit opinions you may not want, including the choice of Renovate over Dependabot, the three-way requirements split and the devcontainer configuration, and you have to undo the ones that do not fit your project. For a repository that will outlive a single evening, those inherited decisions are usually worth it.

What the template cannot give you is the part that makes an integration good, which is the platform code itself, the discovery flow, the configuration flow and the diagnostics. The skeleton is deliberately empty there, and the renames only affect the identifiers. If you were hoping to install a working integration, this is the wrong repository, and the README says so before you read anything else.

Editorial conclusion

Adopt integration_blueprint if you are writing a Home Assistant custom component and want the repository scaffolding, lint job and devcontainer already set up, since copying it saves more time than it costs to configure. Do not adopt it as an integration itself, since the README says plainly that the component and platforms are not meant to be used by a user. Verify first that you rename both identifiers, the integration_blueprint domain and the Integration Blueprint display name, that your domain matches your manifest domain, and that the dependency update tooling you keep is the one you actually want, since the repository ships with Renovate enabled and Dependabot disabled by a leading _ prefix.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. ludeeus/integration_blueprint on GitHub
4. README