SDK Guidelines

Using the Homey Apps SDK should be self-explanatory, yet some things might need some elaboration.

The Homey module

Every class and manager available resides in the Homey module. It should therefore be included in every file of your app.

'use strict';

const Homey = require('homey');

SDK Version

The current SDK version is 2, and you must define this in your /app.json.

Not doing so will result in your app falling back to SDK level 1, which is deprecated.


    "id": "com.athom.example",
    "sdk": 2

Callbacks vs. Promises

All asynchronous methods where a callback Function has been documented, can use either a callback or Promise. The rule is:

  • When a callback argument is passed, and is of type function, then no Promise will be returned.
  • When no callback argument is passed, a Promise will be returned.

At Athom, we favour Promises over Callbacks, as they usually reduce coding errors.

// using promises
    .then( result => {
        // ...
    .catch( err => {
        // ...

// using callbacks
Homey.ManagerFoo.exampleAsyncMethod('my_value', ( err, result ) => {
    if( err ) return; // ...
    // ...