Home Assistant Best Practices

Home Assistant patterns

Prefer native conditions/helpers when they express the intended behavior. Templates remain appropriate for logic native constructs cannot represent. In this repository, Nix owns declarative HA config; UI/config-flow APIs own UI-managed integrations. The generic references below do not transfer that ownership or authorize live changes.

Safety and semantics

• Verify live entity/device identity when a change depends on it; filter reads to relevant fields. If HA is unreachable, continue source-only work where possible and identify what remains unverified rather than inventing IDs.
• Entity renames affect dashboards, scripts, scenes, and config-entry membership; registry renames do not update every consumer. Use supported APIs, not direct .storage edits.
• A wait_for_trigger awaits a future change; a wait_template can complete immediately if already true. They are not interchangeable optimizations.
• Scenes assert desired state; scripts perform sequences. Choose automation mode for retrigger semantics (restart, queued, parallel, single), not one global rule.
• Prefer stable entity IDs; ZHA remotes use device_ieee events, while Z2M autodiscovered device triggers are supported exceptions.

Select a reference

• Entity/helper migration: safe refactoring.
• Triggers, waits, modes, and actions: automation patterns.
• Helper vs template: helper selection and template guidelines.
• YAML-only integrations: configuration.
• Lights, vacuums, Zigbee buttons: device control.
• State snapshots/restoration: scenes.
• Lovelace layout: dashboard guide; individual components: cards.
• Integration/service lookup: domain docs.
• Compound patterns: examples.
• Python lifecycle/timers: AppDaemon.