Homey Apps SDK
📖 Apps SDK Reference🌍 Web API🛠 Developer Tools
  • Welcome to the Apps SDK documentation 👋
  • The Basics
    • Getting Started
      • Homey CLI
    • App
      • Manifest
      • Internationalization
      • Permissions
      • Persistent Storage
    • Drivers & Devices
      • Pairing
        • System Views
          • Devices List
          • Add Devices
          • OAuth2 Login
          • Credentials Login
          • Pincode
          • Loading
          • Done
        • Custom Views
      • Capabilities
      • Energy
      • Settings
      • Best practices
        • Lights
        • Window coverings
        • Battery status
    • Flow
      • Arguments
      • Tokens
    • Widgets
      • Settings
      • Styling
      • Debugging
  • Wireless
    • Wi-Fi
      • Discovery
    • Bluetooth LE
    • Z-Wave
    • Zigbee
    • 433 MHz
    • Infrared
    • Matter
  • Cloud
    • OAuth2
    • Webhooks
  • App Store
    • Publishing
    • Guidelines
    • Verified Developer
    • Updating
  • Advanced
    • Custom Views
      • App Settings
      • Custom Pairing Views
      • HTML & CSS Styling
    • Web API
    • Images
    • LED Ring
    • Homey Compose
  • Guides
    • Homey Cloud
    • Breaking Changes
    • Tools
      • Bluetooth LE
      • Zigbee
      • TypeScript
    • Using ESM in Homey Apps
  • Upgrade Guides
    • Homey v6.0.0
    • Upgrading to SDK v3
      • Zigbee Apps
    • Device Capabilities
Powered by GitBook
On this page
  • App Manifest
  • App Class
  • App API
  • Assets
  • Drivers and Devices
  • Locales
  • Readme
  • Settings
  • Environment
  • Homey Ignore

Was this helpful?

  1. The Basics

App

The essential concepts of a Homey App.

PreviousHomey CLINextManifest

Last updated 9 months ago

Was this helpful?

On this page we will look at what the various files in the Homey app folder are for and what essential concepts you should be aware of to start developing your Homey app.

As of Homey Pro (2016—2019) v7.4.0, Apps run on Node.js v16. Older versions of Homey Pro (2016—2019) run Homey Apps on Node.js v12. Homey Cloud Apps always run on Node.js v16. Homey Pro (Early 2023) Apps run on Node.js v18.

Apps are able to use all of Homey's capabilities and thus can use the following technologies:

Most Apps use only one wireless technology but it is possible to use them all at the same time in a single Homey App. Regardless of the wireless technologies used in your Homey app most of the concepts are the same. Every Homey app has the same basic file structure:

com.athom.example/
├─ .homeycompose/
│ ├─ app.json
│ └─ ...
├─ assets/
│ ├─ icon.svg
│ └─ images
│   ├─ small.png
│   ├─ large.png
│   └─ xlarge.png
├─ drivers/
│ ├─ my_driver/
│ │ ├─ assets/
│ │ │ ├─ icon.svg
│ │ │ └─ images/
│ │ │   ├─ small.png
│ │ │   ├─ large.png
│ │ │   └─ xlarge.png
│ │ ├─ device.js
│ │ └─ driver.js
│ └─ ... 
├─ locales/
│ ├─ en.json
│ └─ nl.json
├─ settings/
│ └─ index.html
├─ api.js
├─ app.js
├─ app.json
├─ env.json
└─ README.txt

App Manifest

The /app.json file is the complete app manifest, it tells Homey what your app does. When you run or publish your app this file is generated from the various *.compose.json files and the JSON files in the /.homeycompose/ folder. The generation of your app manifest is referred to as Homey Compose and it supports some additional advanced features such as templating. All the various compose files will be explained in the rest of the documentation.

Because the /app.json file gets generated from the various Homey Compose files you should never manually edit it. You should edit the *.compose.json and JSON files in the /.homeycompose/ folder instead.

App Class

In the /app.js file you can create an App class. This class gets instantiated once, when your app started. This is a great place to put logic that is shared throughout your app, and it is sometimes necessary for Flow cards and other resources that you only want to setup once.

The app instance can be accessed from your Driver and Device classes through this.homey.app.

/app.js
const Homey = require('homey');
const ApiClient = require('your-external-api-client');

class App extends Homey.App {
  async onInit() {
    // create an ApiClient once when the app is started
    this.client = new ApiClient();
  }
}

module.exports = App;
/drivers/<driver_id>/device.js
const Homey = require('homey');

class Device extends Homey.Device {
  async onInit() {
    // access the ApiClient through the App instance
    const data = await this.homey.app.client.getData();
  }
}

module.exports = Device;

App API

Assets

Drivers and Devices

Locales

Readme

Settings

/app.js
const Homey = require('homey');

class App extends Homey.App {
  async onInit() {
    const username = this.homey.settings.get('username');
    // ...
  }
}

module.exports = App;

Environment

The /env.json file in the root of your app contains the environment variables of your app. Since this file is usually used to store secret keys it should be kept on your computer. If you use Git the /env.json file should therefore be added to the /.gitignore file. In this file you can store information that should not be public, for example the OAuth2 tokens your app uses to connect to a cloud service.

/env.json
{
  "CLIENT_ID": "12345abcde",
  "CLIENT_SECRET": "182hr2389r824ilikepie1302r0832"
}

The variables are available anywhere in your app under Homey.env.CLIENT_ID, Homey.env.CLIENT_SECRET, etc. Make sure they are uppercase, and that their value is a string.

const Homey = require('homey');

const CLIENT_ID = Homey.env.CLIENT_ID;
const CLIENT_SECRET = Homey.env.CLIENT_SECRET;

These variables are stored on Homey, and in theory should not be readable by anyone. However, make sure that these variables alone do not provide access to private resources.

Homey Ignore

The /.homeyignore file in the root of your app can be used to prevent certain files or folders from being included in your Homey App when publishing. It works in the same way as .gitignore. By default all files in the app directory will be included when publishing your Homey App. /.homeyignore is useful in case you want to commit documentation, designs, images, etc. to your version control system but not include it in your Homey App when publishing.

/.homeyignore
comments.txt
docs/*

All basic information about your app is configured in the /.homeycompose/app.json file. You can read the to learn more about this file.

Homey apps can expose an API that other devices can talk to. It is even possible for Homey apps to talk to each other by exposing an API. The /api.js file contains the implementation of all the API endpoints. You can read about exposing an API from your App in the .

In the /assets/ folder at the root of your app you can put the assets of the app. These are the app icon icon.svg and the app images that will be shown in the Homey App Store. Read the for more information about the icon and images.

The /drivers/ folder contains all the drivers of your app. The drivers are the parts of a Homey app that allow users to add and then control devices. This folder should only contain other folders, it is common for those folders to be named after the product code of the device they are implementing. You can learn more by reading the .

Translation files are kept in the /locales/ directory. You can learn more about these files by reading the .

The /README.txt file in the root of your app contains the long-form description of your app. This will be shown in the Homey App Store when a user is browsing your app. Read the for more information about the readme.

You can supply translated versions of the readme by naming the file README.<languagecode>.txt, for example README.nl.txt would contain the Dutch translation of the readme. You can find the supported languages in the .

In your Homey app you can save settings that are persistent across reboots. These settings can be accessed from anywhere in your app through .

You can also create a page where users can update the App Settings by creating an index.html file in the /settings/ folder. Since drivers have their own settings, most apps shouldn't need any App settings. Read more about how and when to use app settings in the .

Wi-Fi
Bluetooth LE
Z-Wave
Zigbee
433 Mhz
Infrared
App Manifest documentation
Web API guide
App Store guidelines
Devices documentation
internationalization documentation
App Store guidelines
internationalization documentation
ManagerSettings
App Settings guide