Philips Hue API Library for Node.js

Common errors

• Error: unable to get local issuer certificate

  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.
  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.

  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.
  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')

  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.
  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.

Warnings

• breaking 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.
  Fix: Rewrite API calls to utilize the v3 Promise-based API. Refer to the official documentation for updated methods and data structures.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install node-hue-api npm
• yarn add node-hue-api yarn
• pnpm add node-hue-api pnpm

Imports

• HueApi
  wrong:

  const HueApi = require('node-hue-api').HueApi;

  correct:

  import { HueApi } from 'node-hue-api';

  The library primarily uses named exports. Prefer ESM imports for modern Node.js environments.
• discovery
  wrong:

  const discovery = require('node-hue-api').discovery;

  correct:

  import { discovery } from 'node-hue-api';

  Use named import for the `discovery` object which contains methods like `upnpSearch` and `nupnpSearch`.
• LightState
  wrong:

  import { LightState } from 'node-hue-api';

  correct:

  import { LightState } from 'node-hue-api/thelper/LightState';

  The `LightState` class is available from a nested helper path, not directly from the root `node-hue-api` module.
• api
  wrong:

  const api = require('node-hue-api');

  correct:

  import * as api from 'node-hue-api';

  When using CommonJS, the entire module is typically imported as a single object. For ESM, a namespace import captures all exports.

Quickstart

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();