File structure
The file structure of your app looks as follows.
com.athom.example
├── README.txt
├── api.js
├── app.js
├── app.json (see "Manifest file" below)
├── assets
│ ├── icon.svg
│ └── images
│ ├── large.png
│ └── small.png
├── drivers
│ └── my_driver
│ ├── assets
│ │ ├── icon.svg
│ │ └── images
│ │ ├── large.png
│ │ └── small.png
│ ├── device.js
│ └── driver.js
├── env.json (see "Environment variable file" below)
├── locales
│ ├── en.json
│ └── nl.json
└── settings
└── index.html
Click a file in the tree to learn more about it.
Manifest file
The App Manifest, a JSON file called /app.json, contains all metadata for your app. It specifies Flow Cards, Drivers, etc.
Example
Most documentation specify their own properties for the /app.json file. An example file is shown below.
/app.json
{
"id": "my.company.example",
"version": "1.0.0",
"compatibility": ">=2.4.0",
"sdk": 3,
"brandColor": "#FF0000",
"name": {
"en": "My App",
"nl": "Mijn App"
},
"description": {
"en": "Adds support for certain devices.",
"nl": "Voegt ondersteuning toe voor bepaalde apparaten."
},
"category": "appliances",
"tags": {
"en": ["example"],
"nl": ["voorbeeld"]
},
"images": {
"large": "/assets/images/large.png",
"small": "/assets/images/small.png"
},
"permissions": ["homey:manager:speech-output", "homey:manager:ledring"],
"author": {
"email": "john@doe.com",
"name": "John Doe"
},
"contributors": {
"developers": [
{
"name": "Alice the Wild",
"email": "alicewild@gmail.com"
}
],
"translators": [
{
"name": "Klemens Kohlmann"
}
]
},
"contributing": {
"donate": {
"paypal": {
"username": "my_paypal.me_username"
}
}
},
"bugs": {
"url": "https://bitbucket.org/athom/com.athom.myapp/issues"
},
"homeyCommunityTopicId": 1234,
"source": "https://github.com/athombv/com.athom.myapp",
"homepage": "https://homey.app",
"support": "mailto:support@homey.app",
"signals": {
// ...
},
"flow": {
"actions": [
{
"id": "my_action",
"title": {
"en": "My Action",
"nl": "Mijn Actie"
}
}
]
},
"drivers": [
{
"id": "my_driver",
"name": {
"en": "My Driver",
"nl": "Mijn Driver"
},
"class": "socket",
"capabilities": ["onoff", "dim"],
"images": {
"large": "/drivers/my_driver/assets/images/large.png",
"small": "/drivers/my_driver/assets/images/small.png"
}
}
],
"capabilities": {
// ...
},
"speech": {
// ...
},
"speechExamples": {
"en": [
// ...
]
},
"screensavers": [
{
"name": "my_screensaver",
"title": {
"en": "My Screensaver"
}
}
]
}
Properties
id
The ID of your app. This is a reversed domain-name.
version
A Semantic Version of your app. Note that pre-release versions (e.g. 1.0.0-rc.1) are not allowed.
compatibility
A Semantic Version indicating a range of Homey versions your app is compatible with.
Use at least "compatibility": ">=1.5.0" (larger or equal than v1.5.0).
sdk
The SDK level of your app. Should be 3.
brandColor
A HEX string for the app's brand color. Colors that are too bright will not be validated. If no brandColor is provided, an unique app color will be automatically generated.
name
An i18n-object with the name of your app.
description
An i18n-object with the description (oneliner) of your app.
category
A string with the Homey App Store category.
Allowed categories are: lights, video, music, appliances, security, climate, tools, internet, localization, energy.
tags
An i18n-object with searchable tags for the App Store.
images
An object containing two paths, small and large.
permissions
An array of Permissions.
author
An object indicating the author of the app. The field author.name is required, author.email is optional.
contributors
An object with developers, following the same format as author.
contributing
An object to show people how to contribute to app development. Only donate.paypal is supported for now, which will show a donate button on the app store page.
bugs
An object with a property url to link to. This is rarely necessary, only when using a non-common Git system.
homeyCommunityTopicId
A number with the discussion ID of the Homey Community. When provided, this shows a link on the App Store. Get the discussion ID from the topic's URL.
source
A string, starting with https://, to link to your app's source code.
homepage
A string, starting with https://, to link to your app's homepage.
support
A string, starting with https:// or mailto:, to link to your app's support website or e-mail address.
signals
See Signals.
flow
See Flow.
drivers
See Drivers.
capabilities
See Capabilities.
speech
See Speech.
speechExamples
See Speech.
screensavers
See LED Ring.
Environment variable file
Sometimes your app must contain information that should not be public. While it is generally a bad idea to embed this in such an application, external services often don't provide a good alternative (for example OAuth2).
It is possible to add environment variables to a Homey app, by placing a /env.json in your app's root, and add it to your .gitignore.
/env.json
{
"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.
The variables are automatically sent to the app store when executed $ homey app publish.
These variables are stored on Homey, and in theory should not be readable by anyone. But keep in mind that no security is 100% safe, ever.