# node-red-contrib-home-assistant-websocket: wiring Node-RED to Home Assistant

> This Node-RED palette connects a Home Assistant instance to your flows over the same websocket API the Home Assistant apps use, with REST alongside it for the calls that need it. It expects Node-RED 3.1.1 or newer, Node.js 20 or newer, and Home Assistant 2024.3 or newer.

**zachowj/node-red-contrib-home-assistant-websocket** — Node-RED integration with Home Assistant

- Repository: https://github.com/zachowj/node-red-contrib-home-assistant-websocket
- Website: https://zachowj.github.io/node-red-contrib-home-assistant-websocket/
- Stars: 603 · Forks: 127
- Language: TypeScript
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/zachowj-node-red-contrib-home-assistant-websocket

## What the palette actually connects

node-red-contrib-home-assistant-websocket provides various nodes to assist in setting up automation using Node-RED communicating with Home Assistant. The package metadata is more precise about the mechanism: it is a Node-RED integration with Home Assistant through websocket and REST API.

That is the key architectural fact. The nodes do not sit beside Home Assistant and poll it. They open the same websocket connection that the Home Assistant companion apps use, subscribe to state changes, and send commands over that same channel, with REST available for the calls that do not fit the websocket model. That is why the dependency list is dominated by the Home Assistant websocket client rather than by anything Home Assistant shaped.

The consequence for a user is that a Node-RED flow can see a state change at the moment it happens and act on it, without polling and without a rest API call per check. The consequence for an operator is that the palette is coupled to an interface Home Assistant controls, so a change on the Home Assistant side is a change for this package too.

The licence is MIT, recorded in the package metadata with the licence file in the repository root, and the documentation is published on a Pages site under the project name rather than in the repository itself.

## The version floors are stated up front

The prerequisites are listed in the README, and they are the first thing to check, because they constrain the whole deployment rather than just the install.

* Node.js v20+
* Node-RED v3.1.1+
* Home Assistant v2024.3+

The package metadata matches. The engines field requires Node 20 or newer, and the node-red block declares a minimum version of 3.1.1 and points the loader at a single entry file.

```json
  "engines": {
    "node": ">=20"
  },
  "packageManager": "pnpm@12.8.2",
```

```json
  "node-red": {
    "version": ">=3.1.1",
    "nodes": {
      "all": "dist/index.js"
    }
  },
```

The Home Assistant floor of 2024.3 is the one that bites in practice. Home Assistant releases every month, so a 2024.3 minimum is not very old, but it does mean the palette is not intended to run against an installation frozen years ago. The Node-RED floor of 3.1.1 matters for a different reason: Node-RED 3.1.1 is the first of the 3.x line, so this palette is a Node-RED 3 package in substance and not only in the metadata.

## Two install routes, and the add-on bundles it

Installation is described in two ways, and there is a third path for add-on users.

The first is the Node-RED Manage Palette, where you search for the package by name and install it from there.

```
node-red-contrib-home-assistant-websocket
```

The second is npm, in the Node-RED user directory, followed by a restart.

```shell
$ cd ~/.node-red
$ npm install node-red-contrib-home-assistant-websocket
# then restart node-red
```

The restart matters. Node-RED loads the node set at start up, so a package installed while the editor is running does not appear in the palette until the process is restarted.

For people who run Node-RED as a Home Assistant add-on, the situation is simpler. The Community add-on ships with this node right out of the box, and the only extra step is a checkbox in the server node configuration.

Under the server node config, check the checkbox for `I use the Home Assistant Add-on`.

The add-on itself lives in the hassio-addons organisation as addon-node-red. The difference in approach is worth noting. The palette and npm routes put the node in a Node-RED that you manage, with your own version and your own upgrade timing. The add-on route ships a Node-RED with this node preinstalled, so the version you get is the version the add-on maintainers chose, and your upgrade path is the add-on's.

## The dependency list is the feature list

The runtime dependencies in the package.json describe what the nodes do, and reading them is faster than reading a feature list.

The protocol client is home-assistant-js-websocket, which is the package that implements the Home Assistant websocket API and the one this project is built on top of. axios handles the REST side. joi is there for configuration validation, which is a sign that the node configuration is typed and checked rather than trusted. cronosjs provides cron style scheduling, so timed triggers are part of the node set. bonjour-service is for local network discovery.

The rest of the list is the usual Node-RED node toolbox: lodash, flat, debug, compare-versions, mustache, selectn and slugify for data handling and templating, geolib for distance and zone work, jsonata for expression evaluation, and lowdb as a small local JSON store.

Two of those deserve a note. lowdb as the local persistence layer is what lets a node keep state between restarts, which matters for flows that count events or debounce. And jsonata as a query language, rather than a homegrown expression syntax, is a deliberate choice about what a user can do inside a message without writing JavaScript.

The project also declares the package manager, pnpm at version 12.8.2, and the repository holds a pnpm-workspace.yaml and a pnpm-lock.yaml, so the development workflow and the published package share one dependency story.

## The repository is set up for continuous releases

The tree shows a project with a settled development process rather than a hobby script, and a few files stand out.

There is a build.mjs at the root that the scripts call, with build running node build.mjs build and dev running node build.mjs start. Documentation is a Vuepress site, with docs:dev, docs:build and a docs:lint script that runs Prettier over the documentation sources.

The quality gates are visible in the script list.

```json
    "test": "vitest --run",
    "test:coverage": "vitest run --coverage",
```

The lint script runs ESLint and a Prettier check over the documentation, source and test directories, and the test runner is Vitest, with a separate coverage command and a watch mode, and there is a vitest.config.ts in the root alongside a .nycrc for coverage settings. Husky is installed by the prepare script, and the lint job runs both ESLint and a Prettier check over the documentation, source and test directories.

Releases are automated too. The repository contains .release-please-manifest.json and release-please-config.json alongside a CHANGELOG.md, which is the release-please setup, and the recent tags follow that pattern: v0.80.3 in November 2025, then v0.81.0 on 2026-10-02 and v0.82.0 on 2026-10-14, with the last push on 2026-10-17.

There is also a .devcontainer directory, a locales/ directory for translations, an icons/ directory for the palette, and an examples/ tree holding a cookbook, a guides folder, a node folder and a diagnostic.json.

## Where this palette is the wrong tool

The first case is a Home Assistant installation without Node-RED. Home Assistant has its own automation editor, and adding a second flow runtime and a websocket bridge to express a rule that the built-in editor already expresses is more moving parts for no gain. The palette is a way to keep the logic in Node-RED, not a way to make Home Assistant more capable.

The second case is a system that must not break when Home Assistant changes. The connection rides on the Home Assistant websocket API and REST API, and the package tracks Home Assistant releases closely enough to have a stated floor of 2024.3. A deployment that upgrades Home Assistant unattended will eventually meet an incompatibility, and the fix lands in this package, not in the installation you control.

The third case is a small script. If the automation is a single trigger and a single action, a shell command or a small script calling the REST API directly is easier to reason about than a flow in a visual editor, and it has no long lived websocket to keep alive.

The alternative worth naming is Home Assistant's own automation layer, and the difference in approach is where the flows live rather than what they can do. A Home Assistant automation is defined inside the Home Assistant interface, against the same entities, and is evaluated by Home Assistant. A Node-RED flow is defined in Node-RED, receives the same state changes over the websocket, and can branch, aggregate, buffer and call anything else on your network. If your logic stays inside the home, the built-in editor is the shorter path. If it needs to talk to other systems, this palette is the way to get that without giving up the state context.

## Conclusion

The palette suits a home automation setup where the logic belongs in Node-RED flows and the state belongs in Home Assistant, especially for someone who already runs both. It does not suit a household that only runs Home Assistant, where the built-in automation editor is the shorter path, and it does not suit an installation you want insulated from Home Assistant changes, because the connection depends on that API staying put. Verify first which Home Assistant version you run, since 2024.3 is the stated floor, and decide how you will install it, because the palette route and the Community add-on route give you different upgrade paths.

## FAQ

### How do I install node-red-contrib-home-assistant-websocket?

Through the Node-RED Manage Palette by searching for the package name, or with npm in the Node-RED directory using cd ~/.node-red followed by npm install node-red-contrib-home-assistant-websocket and then a restart of node-red. Home Assistant add-on users get the node from the Community add-on out of the box.

### Which versions of Node-RED, Node.js and Home Assistant are required?

The README lists Node.js v20 or newer, Node-RED v3.1.1 or newer, and Home Assistant v2024.3 or newer. The package metadata matches with an engines requirement of node >=20 and a node-red version of >=3.1.1.

### I run Node-RED as a Home Assistant add-on. What extra step is there?

Under the server node config you check the checkbox for I use the Home Assistant Add-on. The Community add-on ships with this node included, and the add-on itself is published as hassio-addons/addon-node-red.

### How does the palette talk to Home Assistant?

Through the websocket and REST API, with the websocket client home-assistant-js-websocket as a dependency and axios for REST requests. The README describes the nodes as various nodes to assist in setting up automation using Node-RED communicating with Home Assistant.

### What licence does node-red-contrib-home-assistant-websocket use?

MIT. The package metadata records license MIT and the README links the licence file in the repository root, LICENSE.md.

## Sources

- [License: MIT](https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/LICENSE)
- [Project website](https://zachowj.github.io/node-red-contrib-home-assistant-websocket/)
- [README](https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/README.md)
- [Releases](https://github.com/zachowj/node-red-contrib-home-assistant-websocket/releases)
- [zachowj/node-red-contrib-home-assistant-websocket on GitHub](https://github.com/zachowj/node-red-contrib-home-assistant-websocket)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zachowj-node-red-contrib-home-assistant-websocket