Skip to content

Getting Started

Jump to bottom
Chris Purcell edited this page Feb 7, 2026 · 2 revisions

Getting Started with HA-Dev-Template

This guide will help you get up and running with the Home Assistant Integration Development Template.

Prerequisites

Before you begin, ensure you have:

  • Python 3.14.2 or higher installed
  • Git for version control
  • Home Assistant understanding (basic familiarity)
  • A code editor (VS Code recommended)
  • Terminal/Command line access

Quick Start (5 Minutes)

1. Use This Template

On GitHub, click the "Use this template" button to create your own repository.

2. Clone Your Repository

git clone https://github.com/your-username/your-integration.git
cd your-integration

3. Activate Virtual Environment

The template comes with a pre-configured virtual environment. Just activate it:

Linux/macOS:

source venv/bin/activate

Windows:

venv\Scripts\activate

4. Verify Installation

python scripts/verify_environment.py

You should see all checks pass with green checkmarks (✓).

5. Run Tests

pytest tests/ -v

All tests should pass.

What You Get

After setup, you have:

✅ Complete Python Environment

  • Python 3.14.2 with Home Assistant 2026.2.0
  • All required dependencies pre-installed
  • Development tools configured

✅ Testing Framework

  • pytest with HA custom component support
  • Example test suite
  • Coverage reporting configured

✅ Code Quality Tools

  • Ruff for linting and formatting
  • mypy for type checking
  • pre-commit hooks (install to enable)

✅ Example Integration

  • Working reference implementation
  • Follows HA best practices
  • Includes coordinator, config flow, and entities

✅ CI/CD Pipeline

  • GitHub Actions workflows
  • Automated testing and quality checks
  • Ready for continuous integration

Next Steps

Option A: Study the Example Integration

Explore custom_components/example_integration/ to understand:

  • How DataUpdateCoordinator works
  • Config flow implementation
  • Entity platform setup
  • Testing patterns

Option B: Create Your Own Integration

  1. Copy the example:

    cp -r custom_components/example_integration custom_components/your_integration

  2. Update manifest.json:

    • Change domain to your integration name
    • Update name, documentation, issue_tracker
    • Add your GitHub username to codeowners

  3. Follow the Development Guide for detailed steps

Option C: Enable Pre-commit Hooks (Recommended)

pre-commit install

This automatically runs quality checks before each commit.

Project Structure

HA-Dev-Template/
├── custom_components/          # Your integrations go here
│   └── example_integration/    # Reference implementation
├── tests/                      # Test files
│   ├── conftest.py            # Shared test fixtures
│   └── test_*.py              # Individual test files
├── docs/                       # Documentation
│   ├── QUALITY_CHECKLIST.md   # Quality tier tracking
│   ├── HACS_INTEGRATION.md    # Publishing guide
│   └── ...                    # More guides
├── scripts/                    # Utility scripts
│   └── verify_environment.py  # Environment checker
├── .github/                    # GitHub configuration
│   └── workflows/             # CI/CD pipelines
├── venv/                       # Pre-configured virtual environment
├── pyproject.toml             # Python project config
├── mypy.ini                   # Type checking config
└── README.md                  # Main documentation

Common First Tasks

Task 1: Run the Example Integration Tests

pytest tests/ -v -k example_integration

Task 2: Check Code Quality

# Lint
ruff check custom_components/

# Format
ruff format custom_components/

# Type check
mypy custom_components/example_integration/

Task 3: View CI Pipeline

Go to .github/workflows/ci.yml to see what runs in CI:

  • Linting (Ruff)
  • Formatting checks
  • Type checking (mypy)
  • Tests (pytest)

Task 4: Read Quality Standards

Check docs/QUALITY_CHECKLIST.md to understand Bronze → Platinum tiers.

Troubleshooting Setup

Virtual Environment Not Activating

Symptom: source venv/bin/activate doesn't change your prompt

Solution:

# On Windows, use:
venv\Scripts\activate.bat

# Or PowerShell:
venv\Scripts\Activate.ps1

Import Errors for homeassistant

Symptom: ModuleNotFoundError: No module named 'homeassistant'

Solution:

# Make sure venv is activated (you should see (venv) in prompt)
source venv/bin/activate

# If dependencies are missing, reinstall:
pip install -r requirements.txt

Verification Script Fails

Symptom: verify_environment.py shows red X marks

Solution:

  1. Check which specific checks failed
  2. Most common: virtual environment not activated
  3. If dependencies are missing: pip install -r requirements.txt
  4. Retry verification

Tests Fail on Import

Symptom: Tests can't import custom_components

Solution: This is already fixed in conftest.py, but if you see it:

# Make sure you're in the project root
cd /path/to/your-integration

# Run tests from project root
pytest tests/

Python Version Too Old

Symptom: Verification shows Python < 3.14

Solution:

# Check your Python version
python --version

# Install Python 3.14.2 or higher
# Then recreate venv:
python3.14 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Getting Help

Documentation:

Community:

Resources:

What's Next?

Now that you're set up, continue to:

Happy coding! 🚀

Clone this wiki locally