The `node-hue-api` library provides a comprehensive, Promise-based API for interacting with Philips Hue Bridges from Node.js applications. It abstracts the underlying Hue REST API, offering 100% coverage for both local network and remote internet access. The current stable major version is `v4`, with `v5.0.0-beta.16` actively in development, indicating a consistent update cadence through minor and patch releases. Key differentiators include its robust handling of self-signed bridge certificates for secure local connections, built-in rate limiting to comply with Hue API best practices (since v4.0.0), and full support for modern JavaScript `async/await` patterns. It offers complete control over lights, groups, scenes, sensors, schedules, and bridge configuration.
npm install node-hue-apiVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to discover local Philips Hue Bridges, register a new user (if needed), connect to the API, and then control a light by setting its state.
Rewrite API calls to utilize the v3 Promise-based API. Refer to the official documentation for updated methods and data structures.
Be mindful of your application's API call frequency. Design your logic to minimize rapid, consecutive calls where possible. The rate limit is not currently configurable within the library.
Prefer `createLocal()` for connecting to official Hue Bridges to ensure secure communication and proper certificate validation. Only use `createInsecureLocal()` if explicitly targeting an unofficial or emulated bridge and understand the security implications.
For production applications, use the latest stable `v4.x` release. If you wish to use v5, do so in development environments and monitor the changelog closely for updates.
Ensure you are using `createLocal(host).connect(username)` which includes the library's custom certificate validation logic. Avoid `https.Agent` configurations that might interfere.
If this is the first connection or the username is lost, use the `createUser` method (e.g., `unauthenticatedApi.users.createUser(APP_NAME, DEVICE_NAME)`) to register a new user by pressing the button on the Hue Bridge. Store the generated username securely for future use.
Ensure that `createLocal(host).connect(username)` or `createRemote(clientId, clientSecret, accessToken).connect(username)` has successfully returned a connected `HueApi` instance before attempting to access its properties and methods.
No dependency data recorded yet.