Registry / communication / node-hue-api

node-hue-api

JSON →
library5.0.0-beta.16jsnpmunverified

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-api
INSTALL
IMPORT
SIG · NODE-HUE-API
N
node-hue-api
communicationjavascriptv5.0.0-beta.16
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

HueApi
import { HueApi } from 'node-hue-api';
const HueApi = require('node-hue-api').HueApi;
The library primarily uses named exports. Prefer ESM imports for modern Node.js environments.
discovery
import { discovery } from 'node-hue-api';
const discovery = require('node-hue-api').discovery;
Use named import for the `discovery` object which contains methods like `upnpSearch` and `nupnpSearch`.
LightState
import { LightState } from 'node-hue-api/thelper/LightState';
import { LightState } from 'node-hue-api';
The `LightState` class is available from a nested helper path, not directly from the root `node-hue-api` module.
api
import * as api from 'node-hue-api';
const api = require('node-hue-api');
When using CommonJS, the entire module is typically imported as a single object. For ESM, a namespace import captures all exports.

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.

import { HueApi, discovery, LightState } from 'node-hue-api'; import { createLocal } from 'node-hue-api/dist/esm/api/Api'; const APP_NAME = 'my-node-hue-app'; const DEVICE_NAME = 'my-computer'; async function discoverAndConnect() { let host; try { console.log('Searching for Hue Bridges...'); const discoveryResults = await discovery.upnpSearch(3000); if (discoveryResults.length === 0) { console.log('No bridges found via UPnP. Trying nUPnP...'); const nupnpResults = await discovery.nupnpSearch(); if (nupnpResults.length === 0) { throw new Error('No Hue Bridges found on the network.'); } host = nupnpResults[0].ipaddress; } else { host = discoveryResults[0].ipaddress; } console.log(`Found bridge at ${host}`); const savedUsername = process.env.HUE_USERNAME ?? ''; // Or load from a config file let username = savedUsername; if (!username) { console.log('No username found, registering new user...'); const unauthenticatedApi = createLocal(host).get.</unauthenticatedApi> username = await unauthenticatedApi.users.createUser(APP_NAME, DEVICE_NAME); console.log(`New user created: ${username}. Save this for future use.`); } else { console.log(`Using existing username: ${username}`); } const hueApi = createLocal(host).connect(username); console.log('Successfully connected to the Hue Bridge.'); // Example: Set a light state const lights = await hueApi.lights.getAll(); if (lights.length > 0) { const firstLightId = lights[0].id; console.log(`Setting first light (${lights[0].name}) to a random color and brightness.`); const state = new LightState() .on() .brightness(50 + Math.floor(Math.random() * 50)) // 50-100% .hue(Math.floor(Math.random() * 65535)); // Random hue await hueApi.lights.setLightState(firstLightId, state); console.log('Light state updated.'); } else { console.log('No lights found to control.'); } } catch (err) { console.error(`Error during discovery or connection: ${err.message}`); } } discoverAndConnect();
Debug
Known issues
breakingThe v2 API, its shim, and associated modules were removed in v4.0.0. Projects upgrading from versions prior to v4 will need to update their code to use the v3 API exclusively.
fix
Rewrite API calls to utilize the v3 Promise-based API. Refer to the official documentation for updated methods and data structures.
affects: >=4.0.0
gotchaSince v4.0.0, the library introduces internal rate limiting to comply with Philips Hue API best practices, defaulting to 12 requests per second. While this prevents overloading the bridge from this library, other software on your network accessing the bridge might still cause issues.
fix
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.
affects: >=4.0.0
gotchaConnecting to the Hue Bridge over HTTP using `createInsecureLocal()` will output warnings. This method bypasses the library's custom TLS certificate validation and is primarily intended for use with emulated Hue Bridges, not official hardware.
fix
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.
affects: >=3.0.0
gotchaThe package is currently in a `beta` release phase (v5.0.0-beta.x). While actively developed, beta versions may contain bugs, incomplete features, or further breaking changes before a stable v5 release. It is not recommended for production environments.
fix
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.
affects: >=5.0.0-beta.0
Errors
Common errors & fixes
Error: unable to get local issuer certificate
This error or similar certificate validation failures can occur when Node.js cannot properly validate the self-signed TLS certificate presented by the local Hue Bridge without the library's custom handling.
fix
Ensure you are using `createLocal(host).connect(username)` which includes the library's custom certificate validation logic. Avoid `https.Agent` configurations that might interfere.
Error: 'username' not found, please ensure you have registered this username with the Hue Bridge.
The Hue Bridge requires a registered username (API key) for most API operations. This error typically means the provided username is invalid, not registered, or the bridge has been factory reset.
fix
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.
TypeError: Cannot read properties of undefined (reading 'lights')
This often happens if you try to use API methods (like `lights.getAll()`) on an API object that hasn't been properly connected or authenticated.
fix
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.
Upgrade
Version history
5.0.0-beta.16latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
17 hits · last 30 days
node
14
OpenAI (training)
1
Resources