depot/pkgs/servers/home-assistant/custom-components/README.md

Packaging guidelines

buildHomeAssistantComponent

Custom components should be packaged using the buildHomeAssistantComponent function, that is provided at top-level. It builds upon buildPythonPackage but uses a custom install and check phase.

Python runtime dependencies can be directly consumed as unqualified function arguments. Pass them into propagatedBuildInputs, for them to be available to Home Assistant.

Out-of-tree components need to use Python packages from home-assistant.python.pkgs as to not introduce conflicting package versions into the Python environment.

Example Boilerplate:

{ lib
, buildHomeAssistantComponent
, fetchFromGitHub
}:

buildHomeAssistantComponent {
  # owner, domain, version

  src = fetchFromGithub {
    # owner, repo, rev, hash
  };

  propagatedBuildInputs = [
    # python requirements, as specified in manifest.json
  ];

  meta = with lib; {
    # changelog, description, homepage, license, maintainers
  };
}

Package attribute

The attribute name must reflect the domain as seen in the manifest.json, which in turn will match the python module name below in the custom_components/ directory.

Example:

The project mweinelt/ha-prometheus-sensor would receive the attribute name "prometheus_sensor", because both domain in the manifest.json as well as the module name are prometheus_sensor.

Package name

The pname attribute is a composition of both owner and domain.

Don't set pname, set owner and domain instead.

Exposing the domain attribute separately allows checking for conflicting components at eval time.

Manifest check

The buildHomeAssistantComponent builder uses a hook to check whether the dependencies specified in the manifest.json are present and inside the specified version range. It also makes sure derivation and manifest agree about the domain name.

There shouldn't be a need to disable this hook, but you can set dontCheckManifest to true in the derivation to achieve that.