Skip to content

Home

Jump to bottom
Nerivec edited this page Sep 3, 2025 · 27 revisions

Getting the latest updates

Use dev branch of Zigbee2MQTT: https://www.zigbee2mqtt.io/advanced/more/switch-to-dev-branch.html

Using your current Zigbee2MQTT version

Caution

Some updates will require a minimum version (commit) of Zigbee2MQTT to work properly. This is usually the case when a new feature is introduced and changes are needed in the frontend. See the Zigbee2MQTT dev branch changelog.

Tip

You can install a specific WindFront version using the format pnpm i [email protected], example: pnpm i [email protected]

Baremetal

Stop Zigbee2MQTT.

Inside your Zigbee2MQTT installation folder:

pnpm update zigbee2mqtt-windfront --no-optional

Start Zigbee2MQTT again.

Container

Example with Docker:

docker exec -it CONTAINER_ID sh
apk add npm
npm install -g [email protected]
/usr/local/bin/pnpm update zigbee2mqtt-windfront --no-optional
exit
docker restart CONTAINER_ID

Note: the pnpm version should be the same as used by Zigbee2MQTT:

Standalone serving (with multi-Zigbee2MQTT support)

You can run WindFront in a separate instance (independently of Zigbee2MQTT). This allows you to control the serving in more details and you can also use the same interface for multiple Zigbee2MQTT instances (switch available in the nav bar).

Important

Frontend needs to be enabled in the targeted Zigbee2MQTT instances.

Caution

Some updates will require a minimum version (commit) of Zigbee2MQTT to work properly. This is usually the case when a new feature is introduced and changes are needed in the frontend. See the Zigbee2MQTT dev branch changelog.

Tip

You can install a specific WindFront version using the release tags. For containers: https://github.com/Nerivec/zigbee2mqtt-windfront/pkgs/container/zigbee2mqtt-windfront/versions?filters%5Bversion_type%5D=tagged and for baremetal: https://github.com/Nerivec/zigbee2mqtt-windfront/tags

Docker

https://github.com/Nerivec/zigbee2mqtt-windfront/pkgs/container/zigbee2mqtt-windfront

The container is based on nginx:alpine-slim.

Two tags are available latest (last released version) and edge (development version), along with version-specific tags (see link above).

Configure environment variables

Make sure to configure docker-compose.yml to fit your needs (or using whatever system you use to start the Docker container).

  • Z2M_API_URLS allows to specify the addresses of the Zigbee2MQTT instances that will be available to pick from (comma-separated values, no space, first is default). Example: Z2M_API_URLS=one.local:8080/api,two.local:8080/api
  • Z2M_API_NAMES will label the corresponding URLs (if not supplied, labels will be URLs)
  • USE_PROXY=true if you need tunneling support
docker compose up -d zigbee2mqtt-windfront

WindFront should now be accessible at whatever location you configured (default: localhost:80).

Important

Always provide API URLs without protocol: <hostOrIP>:<port></pathIfAny>/api

Updating

docker compose pull zigbee2mqtt-windfront
docker compose up -d zigbee2mqtt-windfront

Home Assistant

An add-on is available: https://github.com/Nerivec/ha-zigbee2mqtt-windfront

You have to configure the API URLs and names in the add-on "Configuration" tab.

If wanting to include a Zigbee2MQTT add-on instance from within the same Home Assistant machine use the following URL (based on which add-on you use):

  • 45df7312-zigbee2mqtt:8099/api => for use with Zigbee2MQTT release add-on
  • 45df7312-zigbee2mqtt-edge:8099/api => for use with Zigbee2MQTT edge add-on
add-on-config-eg

If using a custom Zigbee2MQTT repository, you will have to use whatever that add-on has for hostname (hostnames are statically assigned based on the repository of the add-on):

z2m-hostname

Tip

An edge version is available to test the latest unreleased changes.

Baremetal

Environment variables are the same as the Docker setup, except with VITE_ prefix: VITE_Z2M_API_URLS, VITE_Z2M_API_NAMES.

git clone --depth 1 https://github.com/Nerivec/zigbee2mqtt-windfront/
npm ci
# example: VITE_Z2M_API_URLS=localhost:5173/api,localhost:8080/api VITE_Z2M_API_NAMES=one,two npm run build
<ENVS> npm run build

Tip

You can pass the argument -b v0.0.0 to git clone to get a specific version (see: https://github.com/Nerivec/zigbee2mqtt-windfront/tags)

The content of the dist folder that will be created can then be served by your favorite software (nginx, etc.).

Updating

git pull
npm ci
<ENVS> npm run build
Clone this wiki locally