Registry / smart-home / homeassistant-ws

homeassistant-ws

library0.2.5jsnpmunverified

Minimalist WebSocket client library for Home Assistant's websocket API. Current stable version is 0.2.5. It provides a simple async interface to connect, authenticate, and interact with Home Assistant, including fetching states, services, panels, config, media player thumbnails, camera thumbnails, calling services, and subscribing to events. Works in Node.js and browsers. Ships TypeScript types. Key differentiators: minimal dependencies, straightforward API, built-in event system for state_changed and other HA events.

smart-home

npm install homeassistant-ws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HOMEASSISTANT-WS

homeassistant-ws

smart-homejavascriptv0.2.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import hass from 'homeassistant-ws';

✗ const hass = require('homeassistant-ws');

Package is ESM-only; default export is a function that returns a client instance.

hass

✓ import hass from 'homeassistant-ws';

✗ import { hass } from 'homeassistant-ws';

Use default import, not named import.

Client

✓ import hass from 'homeassistant-ws'; const client = await hass({...});

✗ import { Client } from 'homeassistant-ws'; const client = new Client({...});

No named export 'Client'; the default export is the factory function.

Connects to Home Assistant using a token, fetches all states, turns on a light, subscribes to state changes, then disconnects.

import hass from 'homeassistant-ws'; async function main() { const token = process.env.HASS_TOKEN ?? 'YOUR_TOKEN'; const client = await hass({ token }); // Get all states const states = await client.getStates(); console.log('States:', states); // Call a service await client.callService('light', 'turn_on', { entity_id: 'light.living_room' }); // Listen for state changes client.on('state_changed', (event) => { console.log('State changed:', event.data.new_state); }); // Disconnect when done client.close(); } main().catch(console.error);

Debug

Known issues

gotchaThe default export function is async and must be awaited to get the client instance.

fix

Use await hass({...}) or .then() to get the client.

affects: >=0.0.0

gotchaIn browser environments, the global WebSocket constructor is used automatically, but you can override via the ws option if needed.

fix

Ensure a WebSocket polyfill is available if targeting older browsers.

affects: >=0.0.0

gotchaThe token option is required if Home Assistant expects authentication, but the library will attempt to connect without if token is null.

fix

Provide a token from your HA profile page for authenticated access.

affects: >=0.0.0

gotchaThe client's close() method only disconnects the WebSocket; it does not clean up event listeners. This may cause memory leaks if the client is recreated.

fix

Remove event listeners before calling close(), or use a single long-lived client instance.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'homeassistant-ws'

Package not installed or not in node_modules.

fix

Run 'npm install homeassistant-ws'.

TypeError: hass is not a function

Using named import instead of default import. Package exports a function as default.

fix

Use import hass from 'homeassistant-ws' instead of import { hass } from 'homeassistant-ws'.

Error: connect ECONNREFUSED ::1:8123

Home Assistant WebSocket server not running at the default address or port.

fix

Ensure Home Assistant is running, or provide correct host/port in options.

Upgrade

Version history

0.2.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/filp/homeassistant-ws ↗

packagehomeassistant-ws ↗

homepagehttps://github.com/filp/homeassistant-ws ↗