# node-hue-api: a Hue bridge client that stopped being maintained > node-hue-api wraps the Philips Hue Bridge REST API in a promise based Node.js library with built in rate limiting and certificate handling for the self signed bridge certificate. Its own note says the repository is no longer being actively maintained, and the newest published release on npm is v4.0.8 from 2020 while the repository sits on a 5.0.0 beta. **peter-murray/node-hue-api** — Node.js Library for interacting with the Philips Hue Bridge and Lights - Repository: https://github.com/peter-murray/node-hue-api - Stars: 1,196 · Forks: 137 - Language: TypeScript - License: Apache-2.0 - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/peter-murray-node-hue-api ## The bridge certificate is self signed, and the library inspects it Connections to a Hue Bridge are made over TLS by default, which is unusual for a local device. The bridge presents a self signed certificate, so ordinary certificate validation fails. The library works around that in a specific way rather than by skipping validation: it processes the certificate, checks the issuer and the subject, and only then allows the TLS connection to proceed. The certificate subject and issuer are the bridge identity itself, for example a country code of NL and an organization of Philips Hue. The remote path is different. When the library talks to the remote Hue API, the certificate is validated normally, because the site at api.meethue.com carries an externally valid certificate and CA chain. So the same library has two certificate policies, and only the local one needs the workaround. There is a third path, and it is the one to be careful with. The function createInsecureLocal() connects over plain HTTP, and the library prints warnings on the console that the connection is insecure. The stated reason is legitimate: some software pretends to be a Hue Bridge, and a self signed certificate would break against it. The cost is that the bridge link is unencrypted and unauthenticated, so a user of that mode has no protection against anyone who can reach the address. The insecure mode is opt in, which is the right shape for it, but the decision belongs to the application, not to the library. ## Three rate limiters run at fixed speeds that cannot be changed From version 4.0 onwards the library throttles its own calls in three places, and the numbers are hard coded. Calls for the library as a whole are limited to 12 per second. Calls made through lights.setLightState() are limited to 10 per second. Calls made through groups.setState() are limited to 1 per second. The group limit is the one that will shape an application. One call per second means that any code which loops over rooms and sets each group in turn spends real wall clock time in the loop, and a user watching the lights will see them change one room at a time. The lights limit is the practical ceiling for a room or a floor, and the global limit of 12 per second is what a mixed script eventually hits. None of these defaults are configurable. The stated reason is that the values conform to the best practices in the Hue API documentation, and the suggested route for a caller who needs different behaviour is to raise a support ticket through an issue rather than to pass a number into the API. A team with its own scheduling needs is therefore stuck with a fixed budget, and the only escape is to fork the library or to serialize the calls itself. The limits also only count what this library does. The project is explicit that they do not take into account all access to the bridge, so if any other software is also talking to the same bridge, the two can together overload it with requests. ## Debug mode prints the bridge identity and the request bodies There is a debug switch, and it is switched on with an environment variable rather than an option. Set NODE_DEBUG to a string containing node-hue-api and the library starts printing the details of the conversations it has with the bridge, including the certificate subject, issuer, validity dates and serial number, the URL placeholders, the request headers and the full request body. That output is genuinely useful when a light refuses to change, because it shows the exact URL and payload that went out. It is also the reason the project carries a warning about who can see it, since that output contains sensitive data, among it the MAC address of the bridge, the IP address and the username values. Anyone pasting a debug log into an issue tracker or a chat channel is publishing the address and the account identifier of the household. The warning does not stop at debug mode. The schedule endpoints are described as continuing to expose that kind of information in normal operation, which is the more important half of the note, because a schedule can be created by any ordinary run of the code and not only by a developer who asked for debug output. The debug block also shows the shape of the underlying requests, which is the clearest statement of the protocol: the base URL points at the bridge address on port 443 with the /api path, requests are JSON, and a schedule is a POST with a name, a localtime pattern, a status and a command that names the light address and the method to apply to it. ## Installing the library is one command, and the API is promise based The package is published on npm under the name node-hue-api, and the installation instructions cover the two package managers a Node.js project is likely to use. ```bash $ npm install node-hue-api ``` ```bash $ yarn add node-hue-api ``` After that the entry point is the v3 API, which the project describes as written for native JavaScript promises. That means standard promise chaining with then() and catch() works, and async and await work in your own code, rather than the callback style that the older version of the library used. The change landed with release 4.0.0 in December 2019, and it is the point at which the project states that it reached complete coverage of the Hue REST API. The surface area is wide, and the project keeps one document per area under the docs directory, covering discovery of local bridges, the remote API, users, lights with the light and light state objects, sensors, scenes with their scene and scene light state objects, groups, rules with conditions and actions, resource links, schedules with time patterns, configuration, capabilities and the remote bridge. A reader coming from the Hue documentation will find the same feature list arranged differently, which is the practical value of the library: the request bodies are already shaped, and the objects come back typed. ## Four runtime dependencies, two build targets, and an old Node floor The package manifest is small enough to read in one go, and it explains the shape of the project. The runtime dependencies are @peter-murray/hue-bridge-model at ^2.0.1, which is the shared object model for bridge resources, bonjour at ^3.5.0 for local discovery, bottleneck at ^2.19.5 for the rate limiting, and node-fetch at ^2.6.1 for the HTTP layer. The build script compiles the same sources twice, once with tsconfig.json into CommonJS and once with tsconfig_esm.json into ES modules, and the manifest points the two entry points at dist/cjs/index.js and dist/esm/index.js, with types taken from dist/esm/index.d.ts. The exports field routes import and require to the matching build, so a consuming project can pick up either module system without a bundler alias. The test script runs mocha over the test files in src with ts-node registered, and prepublishOnly runs the build, so a publish cannot happen with a stale dist directory. The engine floor is node >= 12.0.0, and the dev dependencies pin typescript at ^4.5.3, mocha at ^9.1.3, chai at ~4.3.4 and ts-node at ^10.4.0. That Node 12 floor is a genuine constraint for a library whose whole purpose is running inside a home automation service, since a current system will run something much newer and will not run this dependency tree unchanged. The licence is Apache-2.0, so the code can be reused inside a product without a copyleft obligation. ## The published version and the repository version are six years apart The version in the package manifest is 5.0.0-beta.14, and the default branch of the repository is named typescript, which tells you where that work is happening. The published releases tell a different story. The newest one is v4.0.8 from 2020-07-31, before that v4.0.1 from 2019-12-31, and before that v4.0.0 from 2019-12-27. A stable release from the middle of 2020 is what a project installs from npm today, while the repository has been carrying a beta line for years without a matching published version. The reason is stated at the top of the project page in a note block: the repository is no longer being actively maintained, and anyone interested in taking over ownership and moving it forward with the changes needed to support the new APIs should get in touch so the author can pass it on. The last push to the repository was on 2026-07-12, so commits are still landing even though the maintainer position is open. That combination is the one to keep in mind. The code is not dead, and the object model and the rate limiting are still worth reading, but the published artifact and the repository have drifted apart. A team that depends on it is, in practice, choosing to maintain it. ## Where the library is the wrong choice The first case is a project that only needs to set one light on once. The library brings a bridge model, a discovery service, three throttles and a certificate negotiation layer for that, and the rate limiters will shape your code even when you never approach them. A direct HTTPS request to the bridge address with the credentials you already have is smaller, and the Hue API documentation that the project itself points to covers the same endpoints. The second case is a project that needs the new Hue API. The note about the new APIs is the first thing the project says, and the released version predates the current cloud and local API by years, so features added since 2020 are simply absent from the 4.0.8 line. The beta in the repository is where newer work would live, and it is a beta, not a release. The third case is a long lived product with a security review. The bridge uses a self signed certificate, so the library validates the issuer and the subject by hand, the debug output exposes the bridge MAC address, the IP address and the username, and there is an explicit insecure HTTP mode. Each of those is documented, which is more than many clients manage, but each of them is a finding a reviewer will raise, and the fixes live in a fork rather than in a published version. For a home automation hobbyist with one bridge, the library is more than adequate. For a product, the honest comparison is against writing the small set of Hue requests you actually need against the API, or against maintaining this package yourself. ## Conclusion node-hue-api still fits an existing Node.js project that already talks to a Hue Bridge and wants the certificate negotiation, the three rate limiters and the object model for lights, scenes, groups and schedules rather than hand written requests. It is the wrong dependency for a new smart home project, because the project says outright that it is no longer being actively maintained, the newest listed release is v4.0.8 from 2020-07-31, and the 5.0.0 beta in the repository has not been published. Before you depend on it, check two things: that the Hue API version your bridge exposes still matches the endpoints the library calls, and that you are willing to own the package yourself, since the author is explicitly looking for a new maintainer. ## FAQ ### Is node-hue-api still maintained? No. A note at the top of the project page says the repository is no longer being actively maintained and invites a new owner to take it forward. The last push to the repository was on 2026-07-12, but the newest published release is v4.0.8 from 2020-07-31. ### How do I install node-hue-api and how do I call the bridge? Install it with npm install node-hue-api or yarn add node-hue-api, then use the v3 API, which is written for native promises and supports then() and catch() as well as async and await. Coverage of the Hue REST API was completed with release 4.0.0 in December 2019. ### What are the rate limits in node-hue-api and can I change them? From version 4.0 the library limits all calls to 12 per second, calls through lights.setLightState() to 10 per second, and calls through groups.setState() to 1 per second. The defaults are not currently configurable, and the documented route for a different behaviour is to raise a support ticket. ### How do I turn on debug logging for the Hue bridge connection? Define the environment variable NODE_DEBUG with a string that contains node-hue-api. The library then prints the bridge certificate details, the URL placeholders, the headers and the request bodies, and the project warns that this output contains the MAC address of the bridge, the IP address and the username values. ### Can I connect to a Hue bridge over plain HTTP? Yes, through createInsecureLocal(), which the project offers for software that pretends to be a Hue Bridge. It prints warnings on the console that the connection is insecure, because the bridge link is then neither encrypted nor authenticated. ## Sources - [Issues](https://github.com/peter-murray/node-hue-api/issues) - [License: Apache-2.0](https://github.com/peter-murray/node-hue-api/blob/typescript/LICENSE) - [peter-murray/node-hue-api on GitHub](https://github.com/peter-murray/node-hue-api) - [README](https://github.com/peter-murray/node-hue-api/blob/typescript/README.md) - [Releases](https://github.com/peter-murray/node-hue-api/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/peter-murray-node-hue-api