Information and resources for Homebridge plugins.

Create an issue to:

• request verification for your plugin
• request an icon for your verified plugin
• request a transfer into the Homebridge organization (you can choose whether to continue maintaining the plugin)
• request to maintain an unmaintained plugin listed here

More info on these topics can be found below.

The Verified By Homebridge program allows plugin developers to get their plugins reviewed and endorsed by the Homebridge project team.

• Have your plugin reviewed by the Homebridge team.
• Increase the visibility of your plugin.
• Increase the level of trust end users place in your plugin.
• The Verified shield icon will turn green next to your plugin in the Homebridge UI.
• The Donate heart icon will turn pink and enable on your plugin tile in the Homebridge UI.
• Your plugin is bumped to the top of the search results in the Homebridge UI.
• You can optionally upload an icon for your plugin which will be displayed in the Homebridge UI.

The Homebridge project team will check that your plugin meets the verification criteria, which are listed on the Verified Plugins wiki page.

If you would like your plugin verified, please open an issue on this repository and fill in the template. The Homebridge project team will then review your plugin and provide constructive feedback if required.

If you feel that your plugin should replace the verification status of an existing plugin, let us know and this will be dealt with on an individual basis.

If you need assistance meeting the verification requirements, please reach out on the Homebridge Discord.

Once your plugin has been verified you will remain in full control of the GitHub repository and npm package. Your plugin will appear on the 'Verified By Homebridge' plugin list and the 'Verified' badge will appear next to your plugin when the next update to the Homebridge UI is published.

You may optionally add one of the Verified By Homebridge badges to your plugin's README:

[![verified-by-homebridge](https://img.shields.io/badge/_-verified-blueviolet?color=%23491F59&style=flat&logoColor=%23FFFFFF&logo=homebridge)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)

[![verified-by-homebridge](https://img.shields.io/badge/homebridge-verified-blueviolet?color=%23491F59&style=flat)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)

[![verified-by-homebridge](https://img.shields.io/badge/homebridge-verified-blueviolet?color=%23491F59&style=for-the-badge&logoColor=%23FFFFFF&logo=homebridge)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)

If you decide you no longer wish to maintain your plugin, please reach out to the Homebridge team on the Homebridge Discord. We can assist in finding a new owner, or take over the repository until a new maintainer can be found.

Your plugin may be subject to another review or be removed from the verification list when deemed necessary by the Homebridge team - this could be (but not limited to) the following scenarios:

• We notice an increased amount of issues arising from your plugin, which results in a suboptimal experience for the user, for example, a Homebridge crash loop.
• Your plugin has been unmaintained for some time, and a fork or new plugin offering improved functionality is created.

We will generally do our best to contact existing developers of plugins before removing verification status. However, we may immediately remove verification status in (but not limited to) the following scenarios:

• We notice any sort of user analysis tracking in a verified plugin
• A new plugin requests verification which replaces the functionality of any existing plugin, and we notice that the existing plugin has not been maintained for an extended period of time (and we deem it likely that any contact attempt with the developer would be unsuccessful).

See the Unmaintained Plugins wiki page for more information about transferring an unmaintained plugin to the Homebridge project.

See the Unmaintained Plugins wiki page for more information about maintaining an unmaintained plugin, and a current list of plugins that need a new maintainer.

Plugins can declare which transports they publish accessories over, using two package.json keywords alongside the homebridge-plugin keyword:

• supports-hap — the plugin publishes accessories over HAP (HomeKit)
• supports-matter — the plugin registers Matter accessories itself

{
  "keywords": [
    "homebridge-plugin",
    "supports-hap",
    "supports-matter"
  ]
}

If you declare one transport keyword, declare all the transports you support — the Homebridge UI reads a declaration as complete. From Homebridge UI v5.28.0:

• Plugins declaring supports-matter show a Matter badge on their plugin card.
• A plugin declaring supports-matter without supports-hap is treated as Matter-only — its new child bridges default to Matter enabled and HAP disabled, so users are not shown a HAP QR code that would pair an empty bridge.

Only add supports-matter if your plugin registers Matter accessories itself — it is not for plugins that simply produce HAP accessories, since Homebridge can bridge those to Matter regardless.

See the Matter Plugins wiki page for the full convention.

The purpose of this is to help make the plugin installation process faster and more reliable for verified plugins.

Homebridge plugins are published and distributed to the NPM registry and installed using the npm cli tool.

While npm works for the most part, later versions have become increasingly resource hungry and prone to failure on low powered devices with limited RAM and slow disk I/O (such as a Raspberry Pi).

When using npm to install a plugin, it has to individually fetch the metadata, and download, verify and extract the tarball for every dependency a plugin has. This can result in hundreds of HTTP requests every time a plugin is installed or updated. An error during any of these operations will often result in the plugin failing to install or update.

This project pre-bundles verified plugins, making them available to download, with all their dependencies, in a single tarball. Additionally, a SHA256 sum of the tarball is available so the integrity of the bundle can be verified after being downloaded to the user's system.

A plugin installed via a bundle from this repo can be downloaded and installed in seconds, compared to the minutes it might take for some plugins on the same hardware.

Every 24 hours, a job is executed using GitHub Actions to check for updates made to any verified Homebridge plugins.

Plugins that require updates are then:

1. Installed using npm in a clean work directory, post install scripts are disabled;
2. then a .tar.gz bundle is created for the plugin, including all its dependencies;
3. then a .sha256 checksum file is generated for the bundle;
4. finally the resulting tarball and checksum file are uploaded to this repo.

The two most recent versions of a plugin are retained in this repo, older versions are purged automatically.

Bundles are only used on certain systems:

• Debian-based Linux (via apt package): requires apt package update (=>1.0.27)
• Docker: requires image update (=>2022-07-07)
• Synology DSM 7: requires package update via DSM Package Center (=>3.0.7)

When a user requests a plugin to be installed or updated via the Homebridge UI the following workflow is executed:

1. Check if running on a compatible system
2. Check the plugin is verified
3. Check if a download bundle is available for the requested version
4. Download the .sha256 checksum for the bundle
5. Download the .tar.gz tarball
6. Check the integrity of the tarball against the checksum
7. Create a backup of the existing plugin installation (if already installed)
8. Extract the tarball
9. Run npm rebuild in the plugin's root directory to have any post install scripts executed locally
10. Update the local package.json with the plugin and its version

If the extraction, or npm rebuild steps fail, the old version of the plugin will be restored.

If at any step, the process fails, the Homebridge UI will fall back to using npm to complete the installation.

This project may impact the download stats for plugins provided by the NPM registry.

As such download stats are available via the download-statistics.json file. This file contains the total downloads from this repo for each verified plugin, as well as the download count for each version (including old versions that have been purged).

The download-statistics.json file is updated every 24 hours.

If you are accessing the file programmatically, you will need to add a nonce query string to the URL to prevent it being redirected to an older (deleted) version of the file. E.g. /download-statistics.json?nonce=1657193776.

All verified Homebridge plugins are automatically included.

The plugin will be installed directly from the NPM registry instead.

Create a pull request adding your plugin's name to the pluginFilter: string[] array in the src/plugin-tarballs/index.ts file.

The #plugin-development channel in the official Homebridge Discord server is where Homebridge plugin developers can get tips and advice from other developers and the Homebridge project team.

• Thanks to @hjdhjd for the for-the-badge style badge!

Copyright (c) 2024-2026 Homebridge Copyright (c) 2022-2024 oznu

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.