Depuis le 1er juin 2026, Zigbee2MQTT 2.11.0 est disponible. Parmi les changements, un point surprend de nombreux utilisateurs sur les forums : les extensions JavaScript externes ne se chargent plus dans les nouvelles installations. Si vous venez d'installer Z2M 2.11.0 et que vos extensions ou convertisseurs tierces ont disparu — ou si vous préparez la mise à jour depuis 2.10.x —, ce guide démêle exactement ce qui change et ce qu'il faut faire.

Ce qui change dans Zigbee2MQTT 2.11.0 sur les extensions JS

La version 2.11.0 introduit une nouvelle clé de configuration : enable_external_js, placée dans la section advanced de configuration.yaml. Cette option contrôle le chargement des fichiers JavaScript que Z2M lit depuis deux dossiers :

  • data/external_extensions/ — les extensions JS personnalisées
  • data/external_converters/ — les convertisseurs d'appareils non officiellement supportés

Dans les nouvelles installations, enable_external_js vaut désormais false par défaut. Conséquence directe : si vous déposez un fichier JS dans l'un de ces dossiers, il ne sera pas chargé au démarrage de Z2M sans configuration explicite.

La justification est sécuritaire. Les extensions et convertisseurs externes sont du code JavaScript arbitraire exécuté avec les mêmes privilèges que le processus Z2M. Sur une installation Home Assistant OS standard, ce processus a accès au réseau local et au broker MQTT. Tant que vous êtes le seul à déposer ces fichiers, le risque est faible — mais il était nul par défaut avant 2.11.0. Koenkk et le contributeur Nerivec (PR #31826) ont choisi de renverser ce défaut : opt-in explicite pour le code externe, plutôt qu'opt-out.

Suis-je concerné ? Nouvelle installation vs mise à jour depuis 2.10.x

C'est la question centrale, et la réponse dépend de votre situation. La distinction est importante parce que le comportement n'est pas identique selon que vous installez Z2M pour la première fois ou que vous mettez à jour une installation existante.

Cas 1 — Nouvelle installation de Z2M 2.11.0

Si vous installez Zigbee2MQTT pour la première fois, ou si vous avez réinitialisé votre configuration, enable_external_js sera absent de votre configuration.yaml fraîchement généré. Son absence dans une installation fraîche équivaut à false : vos extensions et convertisseurs ne se chargeront pas, même si les fichiers JS sont bien présents dans les bons dossiers.

Vous êtes concerné si vous utilisez des extensions ou des convertisseurs tierces. Il faut ajouter la clé manuellement (procédure détaillée dans la section suivante).

Cas 2 — Mise à jour depuis Z2M 2.10.x ou antérieur

Si vous mettez à jour une installation existante, le comportement est différent. Pour assurer la rétrocompatibilité, Koenkk a prévu que si enable_external_js n'est pas explicitement défini dans votre configuration.yaml, Z2M considère qu'il vaut true — et ce jusqu'à la version 3.0. Vos extensions et convertisseurs continuent de se charger sans aucune modification de votre part.

Vous n'êtes pas affecté immédiatement. Mais c'est le bon moment d'ajouter explicitement enable_external_js: true dans votre configuration si vous utilisez des extensions, pour ne pas être surpris lors du passage futur à Z2M 3.0, où ce défaut de rétrocompatibilité sera supprimé.

Comment vérifier l'état de vos extensions au démarrage

Ouvrez les logs de Zigbee2MQTT (onglet "Journal" dans l'interface du add-on Home Assistant, ou docker logs zigbee2mqtt pour une installation Docker). Si vos fichiers sont bien chargés, vous devriez voir, au niveau info, un message de confirmation pour chaque extension et convertisseur chargé au démarrage — quelque chose du type "Loaded MyExtension" ou une trace indiquant le fichier pris en compte.

Si aucune mention de vos fichiers JS n'apparaît dans les logs alors qu'ils sont bien présents dans les dossiers, enable_external_js est effectivement à false et il faut agir. Si Z2M démarre sans erreur mais ignore silencieusement vos fichiers JS, c'est ce paramètre qui en est la cause.

Procédure de réactivation — ajouter enable_external_js: true

La manipulation prend deux minutes. Elle se fait en deux étapes : modifier configuration.yaml, puis redémarrer Z2M.

Localiser configuration.yaml

L'emplacement varie selon votre type d'installation :

  • Add-on Home Assistant (cas le plus courant) : cliquez sur le bouton "Modifier la configuration" dans l'interface du add-on Z2M, ou naviguez vers /config/zigbee2mqtt/configuration.yaml via l'add-on File Editor ou Studio Code Server.
  • Installation Docker : dans le volume monté sur le conteneur, typiquement ./zigbee2mqtt-data/configuration.yaml selon votre compose.yml.
  • Installation manuelle (Node.js) : dans le dossier data/ à la racine du projet Z2M.

Ajouter la clé dans la section advanced

Ouvrez configuration.yaml et ajoutez ou complétez la section advanced avec la ligne suivante :

advanced:
  enable_external_js: true

Si la section advanced existe déjà dans votre fichier, ajoutez simplement enable_external_js: true en dessous des autres clés existantes, en respectant l'indentation YAML (2 espaces, pas de tabulations). Exemple avec une section advanced préexistante :

advanced:
  log_level: info
  homeassistant_legacy_entity_attributes: false
  enable_external_js: true

Redémarrer et vérifier

Sauvegardez le fichier, puis redémarrez l'add-on (bouton "Redémarrer" dans l'interface du add-on, ou docker compose restart zigbee2mqtt). Vérifiez les logs au démarrage : des messages de confirmation de chargement pour chaque fichier JS doivent réapparaître au niveau info. Si ce n'est toujours pas le cas, vérifiez que :

  • Les fichiers JS sont bien présents dans data/external_extensions/ ou data/external_converters/ (et non dans un sous-dossier).
  • La syntaxe YAML de votre configuration.yaml est correcte — un outil comme yamllint.com permet de vérifier rapidement.
  • Les fichiers JS ne génèrent pas eux-mêmes une erreur à l'import — vérifiez les logs pour une trace d'exception JavaScript.

Extension vs convertisseur externe — quelle différence ?

Les deux types de fichiers JS sont contrôlés par la même option enable_external_js, mais ils servent à des choses différentes. Comprendre la distinction permet de savoir quel dossier utiliser selon votre besoin.

Les extensions externes (data/external_extensions/) étendent le comportement interne de Z2M. Ce sont des classes JavaScript qui héritent de l'extension de base et peuvent accéder aux événements MQTT, aux messages des appareils, aux groupes, à l'état du système. Cas d'usage typique : créer une logique d'automatisation directement dans Z2M — par exemple, déclencher un groupe de lumières sur un attribut spécifique d'un capteur — sans passer par les automatisations Home Assistant. Le dépôt zigbee2mqtt-user-extensions recense des extensions prêtes à l'emploi.

Les convertisseurs externes (data/external_converters/) définissent la façon dont un appareil Zigbee non supporté officiellement est exposé à Z2M : clusters utilisés, entités à créer (occupancy, temperature, switch…), conversions de valeur. Cas d'usage typique : faire fonctionner un device TuYa ou une clé OEM dont la définition n'est pas encore dans zigbee-herdsman-converters. C'est la solution de contournement classique en attendant une PR officielle.

Si vous utilisez l'un ou l'autre — ou les deux —, une seule clé suffit : enable_external_js: true.

Doit-on vraiment réactiver ? La question de la sécurité

Le changement de défaut est motivé par un principe légitime : les fichiers JS externes s'exécutent avec les mêmes droits que le processus Z2M. Sur Home Assistant OS, ce processus a accès à votre réseau local et à l'ensemble des messages MQTT — donc à l'état de vos appareils. Du code mal intentionné dans une extension pourrait, en théorie, avoir un impact réel.

En pratique, le niveau de risque dépend entièrement de la provenance du code :

  • Si vous avez vous-même écrit ou relu les fichiers JS présents dans ces dossiers, le risque est comparable à celui de tout autre script maison sur votre serveur — faible si vous maîtrisez ce que vous déployez.
  • Si vous avez copié un fichier depuis un forum ou un dépôt tiers sans l'auditer, la prudence s'impose — non pas à cause de Z2M, mais parce que c'est du code tiers exécuté sur votre réseau local.

La recommandation pragmatique : si vous n'utilisez aucune extension ni convertisseur JS externe, laissez enable_external_js à false — c'est le comportement le plus sûr et il ne change rien à votre quotidien Z2M. Si vous en avez besoin, activez-le en ayant conscience du code que vous faites tourner.

Les autres nouveautés de Zigbee2MQTT 2.11.0

Au-delà de la gestion des extensions JS, Z2M 2.11.0 apporte plusieurs améliorations pertinentes pour les installations DIY.

GreenPower : meilleur support des interrupteurs sans pile

Le parsing des frames Zigbee Green Power (ZGP) a été étendu. ZGP est le protocole utilisé par les interrupteurs qui récupèrent l'énergie de la pression mécanique — sans pile, sans câble. Les produits Legrand Céliane with Netatmo et Philips Hue Tap utilisent ce protocole. Avec 2.11.0, la reconnaissance des boutons et la distinction des types d'appui (court, long, double pression) sont améliorées pour un plus grand nombre de ces appareils — utile si vous utilisez des interrupteurs sans pile comme déclencheurs d'automation dans Home Assistant.

Support du cluster Zigbee Direct

Z2M 2.11.0 commence à implémenter le support du cluster Zigbee Direct, qui permet des communications directes entre appareils Zigbee compatibles sans passer systématiquement par le coordinateur. C'est encore un début de support — peu d'appareils commerciaux l'implémentent en 2026 — mais c'est une fondation pour les futures devices qui adopteront ce mode de communication.

Nouveaux appareils supportés

Comme à chaque release mineure, la liste des appareils supportés s'élargit. La 2.11.0 ajoute de nouvelles références Shelly Zigbee, Tuya et Aqara, ainsi que des corrections de comportement sur des devices existants. La liste complète figure dans les release notes sur GitHub.

Résumé — ce qu'il faut retenir

Zigbee2MQTT 2.11.0 ne casse pas les extensions des installations existantes qui mettent à jour depuis 2.10.x : elles restent actives par défaut jusqu'à la 3.0. C'est uniquement sur les nouvelles installations fraîches que enable_external_js vaut false par défaut. Si vous êtes dans ce cas et que vous utilisez des extensions ou des convertisseurs JS, ajoutez enable_external_js: true dans la section advanced de votre configuration.yaml, redémarrez Z2M, et tout rentre dans l'ordre. Si vous mettez à jour depuis une version antérieure, aucune action urgente n'est requise — mais c'est le bon moment d'ajouter cette clé explicitement pour anticiper la 3.0.