{"id":16461,"library":"node-hue-api","title":"Philips Hue API Library for Node.js","description":"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.","status":"active","version":"5.0.0-beta.16","language":"javascript","source_language":"en","source_url":"https://github.com/peter-murray/node-hue-api","tags":["javascript","philips","hue","api","living","color","colour","automation","light","typescript"],"install":[{"cmd":"npm install node-hue-api","lang":"bash","label":"npm"},{"cmd":"yarn add node-hue-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-hue-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses named exports. Prefer ESM imports for modern Node.js environments.","wrong":"const HueApi = require('node-hue-api').HueApi;","symbol":"HueApi","correct":"import { HueApi } from 'node-hue-api';"},{"note":"Use named import for the `discovery` object which contains methods like `upnpSearch` and `nupnpSearch`.","wrong":"const discovery = require('node-hue-api').discovery;","symbol":"discovery","correct":"import { discovery } from 'node-hue-api';"},{"note":"The `LightState` class is available from a nested helper path, not directly from the root `node-hue-api` module.","wrong":"import { LightState } from 'node-hue-api';","symbol":"LightState","correct":"import { LightState } from 'node-hue-api/thelper/LightState';"},{"note":"When using CommonJS, the entire module is typically imported as a single object. For ESM, a namespace import captures all exports.","wrong":"const api = require('node-hue-api');","symbol":"api","correct":"import * as api from 'node-hue-api';"}],"quickstart":{"code":"import { HueApi, discovery, LightState } from 'node-hue-api';\nimport { createLocal } from 'node-hue-api/dist/esm/api/Api';\n\nconst APP_NAME = 'my-node-hue-app';\nconst DEVICE_NAME = 'my-computer';\n\nasync function discoverAndConnect() {\n  let host;\n  try {\n    console.log('Searching for Hue Bridges...');\n    const discoveryResults = await discovery.upnpSearch(3000);\n    if (discoveryResults.length === 0) {\n      console.log('No bridges found via UPnP. Trying nUPnP...');\n      const nupnpResults = await discovery.nupnpSearch();\n      if (nupnpResults.length === 0) {\n        throw new Error('No Hue Bridges found on the network.');\n      }\n      host = nupnpResults[0].ipaddress;\n    } else {\n      host = discoveryResults[0].ipaddress;\n    }\n    console.log(`Found bridge at ${host}`);\n\n    const savedUsername = process.env.HUE_USERNAME ?? ''; // Or load from a config file\n    let username = savedUsername;\n\n    if (!username) {\n      console.log('No username found, registering new user...');\n      const unauthenticatedApi = createLocal(host).get.</unauthenticatedApi>\n      username = await unauthenticatedApi.users.createUser(APP_NAME, DEVICE_NAME);\n      console.log(`New user created: ${username}. Save this for future use.`);\n    } else {\n      console.log(`Using existing username: ${username}`);\n    }\n\n    const hueApi = createLocal(host).connect(username);\n    console.log('Successfully connected to the Hue Bridge.');\n\n    // Example: Set a light state\n    const lights = await hueApi.lights.getAll();\n    if (lights.length > 0) {\n      const firstLightId = lights[0].id;\n      console.log(`Setting first light (${lights[0].name}) to a random color and brightness.`);\n      const state = new LightState()\n        .on()\n        .brightness(50 + Math.floor(Math.random() * 50)) // 50-100%\n        .hue(Math.floor(Math.random() * 65535)); // Random hue\n      await hueApi.lights.setLightState(firstLightId, state);\n      console.log('Light state updated.');\n    } else {\n      console.log('No lights found to control.');\n    }\n\n  } catch (err) {\n    console.error(`Error during discovery or connection: ${err.message}`);\n  }\n}\n\ndiscoverAndConnect();","lang":"typescript","description":"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."},"warnings":[{"fix":"Rewrite API calls to utilize the v3 Promise-based API. Refer to the official documentation for updated methods and data structures.","message":"The 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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"Since 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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"Connecting 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=5.0.0-beta.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Error: unable to get local issuer certificate"},{"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.","cause":"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.","error":"Error: 'username' not found, please ensure you have registered this username with the Hue Bridge."},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'lights')"}],"ecosystem":"npm"}