What is the file structure of a Homey App.

Homey apps teach Homey how to talk to other devices. One app often implements all devices from a single manufacturer or brand. Homey apps are written using the Homey Apps SDK. Homey apps are written in JavaScript and run using Node.js on Homey itself.

Homey apps are very powerful: They are able to do anything a "regular" Node.js program can do, such as access the local network and connecting to cloud services. In addition apps are able to use all of Homey's capabilities and thus can use the following technologies:

File Structure

Every Homey app has the same basic file structure:

├─ .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 your app manifest, it tells Homey what your app does. This file is generated from the various *.compose.json files and the JSON files in the /.homeycompose/ folder.

Because the App Manifest gets generated from the various Homey Compose files you should never manually edit the /app.json file.

Homey Compose

The /.homeycompose/ folder contains the JSON files that your App Manifest will be generated from. The precise contents and structure of this folder will be explained in the rest of the documentation. The /.homeycompose/app.json file represents the basis of your app, continue to the next page to learn more about this file.

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

const Homey = require('homey');
const ApiClient = require('your-external-api-client');
class MyApp extends Homey.App {
async onInit() {
// create an ApiClient once when the app is started
this.client = new ApiClient();
module.exports = MyApp;
const Homey = require('homey');
class MyDevice extends Homey.Device {
async onInit() {
// access the ApiClient through the App instance
const data = await;
module.exports = MyDevice;


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 Web API guide.


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 App Store guidelines for more information about the readme.


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 App Store guidelines 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 drivers guide.


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


A Homey App can save settings that are persistent across reboots. These settings can be accessed from anywhere in your app through ManagerSettings.

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

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 App Settings guide.


The /env.json file in the root of your app contains the environment variables of your app. This file should be added to the /.gitignore. 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.

"CLIENT_ID": "12345abcde",
"CLIENT_SECRET": "182hr2389r824ilikepie1302r0832"

The variables are available 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;

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.