ha-integration-scaffold

Home Assistant Integration Scaffolding

Required File Structure

custom_components/{domain}/
├── __init__.py           # Entry point: async_setup_entry, async_unload_entry
├── manifest.json         # Integration metadata (REQUIRED)
├── config_flow.py        # UI-based configuration (REQUIRED)
├── const.py              # Domain constant, platform list
├── coordinator.py        # DataUpdateCoordinator subclass
├── entity.py             # Base entity class (recommended)
├── strings.json          # Config flow strings
├── services.yaml         # Service action definitions (if registering services)
├── icons.json            # Entity and service icons (optional)
├── translations/
│   └── en.json           # English translations
└── [platform].py         # One per entity platform (sensor.py, switch.py, etc.)

For HACS distribution, also include at repository root:

/
├── custom_components/{domain}/   # Integration files
├── hacs.json                     # HACS metadata (REQUIRED for HACS)
├── README.md                     # Documentation
└── LICENSE                       # License file

manifest.json (2025 Requirements)

{
	"domain": "{domain_name}",
	"name": "{Human Readable Name}",
	"version": "1.0.0",
	"codeowners": ["@{github_username}"],
	"config_flow": true,
	"dependencies": [],
	"documentation": "https://github.com/{user}/{repo}",
	"integration_type": "hub",
	"iot_class": "local_polling",
	"issue_tracker": "https://github.com/{user}/{repo}/issues",
	"requirements": []
}

Always required:

• domain: lowercase, underscores only, matches folder name
• name: human-readable
• codeowners: GitHub usernames with @ prefix
• documentation: URL to integration docs
• iot_class: local_polling, local_push, cloud_polling, cloud_push, calculated
• integration_type: most common values are hub (gateway/multiple devices), device (single device), service (cloud service); full set is device, entity (single entity), hardware, helper (logic-only helper), hub, service, system, virtual; defaults to hub when omitted