{"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.","language":"javascript","status":"active","last_verified":"Wed Apr 22","install":{"commands":["npm install node-hue-api"],"cli":null},"imports":["import { HueApi } from 'node-hue-api';","import { discovery } from 'node-hue-api';","import { LightState } from 'node-hue-api/thelper/LightState';","import * as api from 'node-hue-api';"],"auth":{"required":false,"env_vars":[]},"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.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}