TypeScript Home Automation¶
A lightweight, fully typed home automation framework built on MQTT and Bun. Replace Home Assistant automations with testable TypeScript classes — no YAML, no UI, just code.
Why ts-home-automation?¶
- Pure TypeScript — automations are ordinary classes, fully typed end-to-end
- MQTT-native — designed around Zigbee2MQTT with wildcard topic support
- Multiple trigger types — MQTT messages, cron schedules, state changes, webhooks, and Zigbee device events
- Zigbee device registry — automatic device discovery and state tracking; react to any device state change, join, or departure with a single trigger
- Rich service layer — Shelly devices, Nanoleaf panels, weather data, push notifications, HomeKit bridge
- Observable — structured logging, in-memory log buffer, web status page, CLI dashboard
- Kubernetes-ready —
/healthzand/readyzprobes built in
Two ways to use it¶
As an npm package¶
Install ts-home-automation in your own project and bring your own automation files:
Standalone¶
Clone the repo, drop automations into src/automations/, and run:
git clone https://github.com/Supporterino/TypeScript-Home-Automation.git
cd TypeScript-Home-Automation
bun install && bun run dev
Quick links¶
| Getting Started | Install, configure, write your first automation |
| Configuration | All environment variables |
| Writing Automations | Triggers, services, lifecycle hooks |
| API Reference | Complete reference for all public classes, types, and methods |
| Device Registry | Zigbee device discovery, state tracking, nice names |
| Custom Service Plugins | Extend the engine with your own services |
| CLI Reference | ts-ha command reference |
| Web UI | Browser dashboard |
| HomeKit | Apple HomeKit bridge service |
| Deployment & Operations | Docker, Kubernetes, production setup |
| Architecture | How the engine works internally |
| Troubleshooting & FAQ | Common issues and solutions |
| npm package | ts-home-automation on npm |