Skip to content

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 TypeScript 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 — /healthz and /readyz probes built in

Two ways to use it

As an npm package

Install @ts-ha/core in your own project and bring your own automation files:

bun add @ts-ha/core

→ Getting Started

From source

Clone the repo, create an automations/ directory, and run:

git clone https://github.com/Supporterino/TypeScript-Home-Automation.git
cd TypeScript-Home-Automation
bun install && bun run dev
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
Prometheus Metrics Prometheus metrics endpoint
Deployment & Operations Docker, Kubernetes, production setup
Architecture How the engine works internally
Troubleshooting & FAQ Common issues and solutions
npm package @ts-ha/core on npm

Note: This documentation is generated with AI assistance and may contain inaccuracies. Please verify critical information against the source code or by running the commands directly.