homey-api is the official JavaScript client for Athom's Homey Web APIs, providing programmatic access to Homey Pro and Homey Cloud devices. It is actively maintained with the current stable version being 3.18.2, and new releases typically coincide with API updates or bug fixes. The library supports various JavaScript environments including Node.js (requiring Node.js >=24), browsers (via CDN or bundlers), and React Native, as well as specialized in-app usage for Homey Pro. Key differentiators include its official status, comprehensive TypeScript type definitions, and direct support for both local network (Homey Pro) and cloud-based (Homey Cloud) API interactions. Developers must obtain OAuth2 client credentials from Athom to interact with the Web API.
npm install homey-apiVerified import paths — ran on the pinned version, not inferred.
Demonstrates how to connect to a local Homey Pro device using a personal access token and list all connected devices. This requires a `.env` file with `HOMEY_ADDRESS` and `HOMEY_TOKEN`.
Upgrade your Node.js environment to version 24 or newer. Use `nvm` or your preferred Node.js version manager.
For external applications, use `import { HomeyAPI } from 'homey-api';`. If you intend to develop a Homey app, install the `homey` package and refer to the Homey Apps SDK documentation.Register your application in the Homey Developer Tools to get your OAuth2 Client ID and Secret. Implement the OAuth2 flow to obtain access tokens. Request a limit increase if you need to support more than 100 users or connect to Homey Cloud.
Replace `athom-api` with `homey-api` in your `package.json` and update import statements. The core `HomeyAPI` and `AthomCloudAPI` classes remain available.
For ESM, use `import { AthomCloudAPI } from 'homey-api';`. Ensure you are installing `homey-api` for external clients, not the `homey` SDK package.Ensure `HomeyAPI` is imported as a named export: `import { HomeyAPI } from 'homey-api';`.Ensure your Node.js environment meets the `>=24` requirement. If still problematic, investigate potential polyfill conflicts or environment-specific issues with `fetch` and `AbortController`.
Generate a new personal access token from the Homey Web App and ensure it is correctly configured as `HOMEY_TOKEN` in your environment variables. Verify the `HOMEY_ADDRESS` is correct and the Homey is online.
No dependency data recorded yet.