TypeScript Home Automation

A lightweight, fully typed home automation framework built on MQTT and Bun. Write automations as TypeScript classes — no YAML, no UI, just code.

→ Full documentation

This project is developed with the assistance of AI tools (code generation, documentation, and testing).

---

Install

bun add ts-home-automation

Or clone and run standalone:

git clone https://github.com/Supporterino/TypeScript-Home-Automation.git
cd TypeScript-Home-Automation && bun install && bun run dev

Requires Bun and an MQTT broker (e.g. Mosquitto).

---

Quick start

// src/index.ts
import { createEngine } from "ts-home-automation";

const engine = createEngine({
  automationsDir: new URL("./automations", import.meta.url).pathname,
});
process.on("SIGINT", async () => { await engine.stop(); process.exit(0); });
await engine.start();

// src/automations/motion-light.ts
import { Automation, type Trigger, type TriggerContext, type OccupancyPayload } from "ts-home-automation";

export default class MotionLight extends Automation {
  readonly name = "motion-light";
  readonly triggers: Trigger[] = [
    { type: "mqtt", topic: "zigbee2mqtt/hallway_sensor",
      filter: (p) => (p as OccupancyPayload).occupancy === true },
  ];
  async execute(_ctx: TriggerContext): Promise<void> {
    this.mqtt.publishToDevice("hallway_light", { state: "ON", brightness: 254 });
  }
}

---

Key environment variables

Variable	Default	Description
MQTT_HOST	localhost	MQTT broker hostname
LOG_LEVEL	info	trace · debug · info · warn · error
HTTP_PORT	8080	HTTP server port (0 = disabled)
WEB_UI_ENABLED	false	Enable the web UI dashboard
DEVICE_REGISTRY_ENABLED	false	Enable Zigbee device discovery and state tracking

See Configuration for all variables.

---

Documentation

Getting Started	Install, configure, first automation
Writing Automations	Triggers, services, lifecycle hooks
API Reference	All public classes, types, and methods
Device Registry	Zigbee device discovery, state tracking, nice names
Configuration	All environment variables
CLI Reference	ts-ha commands
Web UI	Browser dashboard
Deployment	Docker, Kubernetes, production setup
Architecture	How the engine works
Troubleshooting	Common issues and solutions
Contributing	Dev setup, conventions

---

License

GPL-3.0