3 files changed, 26 insertions, 9 deletions
diff --git a/pkgs/servers/home-assistant/custom-components/README.md b/pkgs/servers/home-assistant/custom-components/README.md
index a7244b25c173..d7137e5c62f7 100644
--- a/pkgs/servers/home-assistant/custom-components/README.md
+++ b/pkgs/servers/home-assistant/custom-components/README.md
@@ -25,7 +25,7 @@ versions into the Python environment.
 }:
 
 buildHomeAssistantComponent {
-  # pname, version
+  # owner, domain, version
 
   src = fetchFromGithub {
     # owner, repo, rev, hash
@@ -40,18 +40,34 @@ buildHomeAssistantComponent {
   }
 }
 
-## Package name normalization
+## Package attribute
 
-Apply the same normalization rules as defined for python packages in
-[PEP503](https://peps.python.org/pep-0503/#normalized-names).
-The name should be lowercased and dots, underlines or multiple
-dashes should all be replaced by a single dash.
+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](https://github.com/mweinelt/ha-prometheus-sensor/blob/1.0.0/custom_components/prometheus_sensor/manifest.json#L2)
+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.
+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.
diff --git a/pkgs/servers/home-assistant/custom-components/default.nix b/pkgs/servers/home-assistant/custom-components/default.nix
index 4a96b305964a..15bd721c72e8 100644
--- a/pkgs/servers/home-assistant/custom-components/default.nix
+++ b/pkgs/servers/home-assistant/custom-components/default.nix
@@ -2,5 +2,5 @@
 }:
 
 {
-  prometheus-sensor = callPackage ./prometheus-sensor {};
+  prometheus_sensor = callPackage ./prometheus_sensor {};
 }
diff --git a/pkgs/servers/home-assistant/custom-components/prometheus-sensor/default.nix b/pkgs/servers/home-assistant/custom-components/prometheus_sensor/default.nix
index 07bcd9abec1c..2368d85552b2 100644
--- a/pkgs/servers/home-assistant/custom-components/prometheus-sensor/default.nix
+++ b/pkgs/servers/home-assistant/custom-components/prometheus_sensor/default.nix
@@ -4,7 +4,8 @@
 }:
 
 buildHomeAssistantComponent rec {
-  pname = "prometheus-sensor";
+  owner = "mweinelt";
+  domain = "prometheus_sensor";
   version = "1.0.0";
 
   src = fetchFromGitHub {