# Manifest

The App Manifest contains all metadata for your app. It specifies Flow Cards, Drivers, etc.

{% tabs %}
{% tab title="JavaScript" %}
{% code title="/.homeycompose/app.json" %}

```json
{
  "id": "my.company.example",
  "version": "1.0.0",
  "compatibility": ">=5.0.0",
  "runtime": "nodejs",
  "platforms": ["local", "cloud"],
  "sdk": 3,
  "brandColor": "#FF0000",
  "name": { "en": "My App" },
  "description": { "en": "Adds support for Example devices." },
  "category": "lights",
  "tags": { "en": ["example"] },
  "images": {
    "small": "/assets/images/small.png",
    "large": "/assets/images/large.png",
    "xlarge": "/assets/images/xlarge.png"
  },
  "permissions": ["homey:manager:api"]
  "author": {
    "email": "john@doe.com",
    "name": "John Doe"
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="TypeScript" %}
{% code title="/.homeycompose/app.json" %}

```json
{
  "id": "my.company.example",
  "version": "1.0.0",
  "compatibility": ">=5.0.0",
  "runtime": "nodejs",
  "platforms": ["local", "cloud"],
  "sdk": 3,
  "brandColor": "#FF0000",
  "name": { "en": "My App" },
  "description": { "en": "Adds support for Example devices." },
  "category": "lights",
  "tags": { "en": ["example"] },
  "images": {
    "small": "/assets/images/small.png",
    "large": "/assets/images/large.png",
    "xlarge": "/assets/images/xlarge.png"
  },
  "permissions": ["homey:manager:api"]
  "author": {
    "email": "john@doe.com",
    "name": "John Doe"
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code title="/.homeycompose/app.json" %}

```json
{
  "id": "my.company.example",
  "version": "1.0.0",
  "compatibility": ">=13.0.0",
  "runtime": "python",
  "pythonVersion": "3.14",
  "pythonDependencies": [],
  "platforms": ["local", "cloud"],
  "sdk": 3,
  "brandColor": "#FF0000",
  "name": { "en": "My App" },
  "description": { "en": "Adds support for Example devices." },
  "category": "lights",
  "tags": { "en": ["example"] },
  "images": {
    "small": "/assets/images/small.png",
    "large": "/assets/images/large.png",
    "xlarge": "/assets/images/xlarge.png"
  },
  "permissions": ["homey:manager:api"]
  "author": {
    "email": "john@doe.com",
    "name": "John Doe"
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Properties

<table data-header-hidden><thead><tr><th width="213">Name</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>Description</td></tr><tr><td><code>id</code></td><td>The ID of your app. This is a reversed domain-name.</td></tr><tr><td><code>version</code></td><td>A <a href="http://semver.org">Semantic Version</a> of your app. Note that pre-release versions (e.g. <code>1.0.0-rc.1</code>) are not allowed.</td></tr><tr><td><code>compatibility</code></td><td>A <a href="http://semver.org">Semantic Version</a> indicating a range of Homey versions your app is compatible with. Use at least <code>"compatibility": ">=5.0.0"</code> (larger or equal than v5.0.0).</td></tr><tr><td><code>runtime</code></td><td>The runtime the app is written for. Allowed runtimes are <code>nodejs</code> and <code>python</code>.</td></tr><tr><td><code>platforms</code></td><td>An array containing the app's supported platforms. Read the <a href="../../guides/homey-cloud">Homey Cloud</a> guide for more information.</td></tr><tr><td><code>sdk</code></td><td>The SDK level of your app. Should be <code>3</code>.</td></tr><tr><td><code>brandColor</code></td><td>A HEX string for the app's brand color. The brand color is not allowed to be very bright.</td></tr><tr><td><code>name</code></td><td>A <a href="internationalization">translation object</a> with the name of your app.</td></tr><tr><td><code>description</code></td><td>A <a href="internationalization">translation object</a> with the description (oneliner) of your app.</td></tr><tr><td><code>category</code></td><td>A string with the Homey App Store category. Allowed categories are: <code>lights</code>, <code>video</code>, <code>music</code>, <code>appliances</code>, <code>security</code>, <code>climate</code>, <code>tools</code>, <code>internet</code>, <code>localization</code>, <code>energy</code>.</td></tr><tr><td><code>tags</code></td><td>A <a href="internationalization">translation object</a> with searchable tags for the App Store.</td></tr><tr><td><code>images</code></td><td>An object containing two paths, <code>small</code> and <code>large</code>, and optionally a third: <code>xlarge</code>.</td></tr><tr><td><code>permissions</code></td><td>An array of <a href="permissions">Permissions</a>.</td></tr><tr><td><code>author</code></td><td>An object indicating the author of the app. The field <code>author.name</code> is required, <code>author.email</code> is optional.</td></tr></tbody></table>

## Python properties

The following app manifest properties are only required for apps using the Python runtime.

### Python version

A string with the Python version the app was developed for. Currently the only supported version is `3.14`.

```jsonc
{
  "id": "com.athom.example",
  // ...
  "runtime": "python",
  "pythonVersion": "3.14",
}
```

{% hint style="warning" %}
If the given version becomes outdated with the version(s) available on the Homey platforms, a newer version may be used to run the Homey app, which may result in incompatibility. When a new full-release Python version becomes available apps have about a year to update to the new version.
{% endhint %}

### Python dependencies

To keep track of the dependencies of the Homey app, and to allow for checking compatibility with Homey platforms, any libraries added as a dependency through the CLI will be stored in the app manifest.

```jsonc
{
  "id": "com.athom.example",
  // ...
  "runtime": "python",
  "pythonDependencies": [
    "aiohttp>=3.13"
  ],
}
```

{% hint style="danger" %}
Editing the dependencies in the app manifest without running `homey app dependencies install` results in the app being bundled with outdated libraries.
{% endhint %}

{% hint style="warning" %}
Installing dependencies through other means than `homey app dependencies install` results in those dependencies missing in the bundled app. Always test your app by installing it or running it remotely if you have changed the dependencies, in order to see whether they are bundled correctly.
{% endhint %}

## Additional properties

The following app manifest properties are optional but can be used to document extra information about your app. Most of this information will be presented to users in the Homey App Store.

### Platform Local Required Features

An array of required features (`nfc`, `ledring`, `speaker` or `matter`) for platform `local`. Adding a required feature will make the app uninstallable on Homey Pros that do not have all the listed features. So only use this when the app will only function with the respective feature.

```jsonc
{
  "id": "com.athom.example",
  // ...
  "platformLocalRequiredFeatures": [ "nfc", "speaker", "ledring" ]
}
```

### Contributors

An object with keys `developers` and `translators`. Each object in the `developers` or `translators` array must contain a `name` property.

{% code title="/.homeycompose/app.json" %}

```jsonc
{
  "id": "com.athom.example",
  // ...
  "contributors": {
    "developers": [
      {
        "name": "Alice the Wild"
      }
    ],
    "translators": [
      {
        "name": "Klemens Kohlmann"
      }
    ]
  }
}
```

{% endcode %}

### Contributing

Perhaps some users want to show their appreciation for your hard work in the form of a small donation.

When adding one or more donation options to your app's manifest, a *Donate* button will appear on your app's page.

![](https://998911913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPk9cn4V7WnnKt7fbry%2Fuploads%2Fgit-blob-41df58757264425232d691ef6342bfe9e596b581%2Fdonate.png?alt=media)

{% hint style="info" %}
Donate buttons are only visible for non-verified developers.
{% endhint %}

{% code title="/.homeycompose/app.json" %}

```jsonc
{
  "id": "com.athom.example",
  // ...
  "contributing": {
    "donate": {
      "paypal": {
        // Will link to https://paypal.me/my_paypal_username
        "username": "my_paypal_username"
      },
      "bunq": {
        // Will link to https://bunq.me/my_bunq_username
        "username": "my_bunq_username"
       },
       "patreon": {
         // Will link to https://www.patreon.com/my_patreon_username
         "username": "my_patreon_username"
       },
       "githubSponsors": {
         // Will link to https://github.com/sponsors/my_github_username
         "username": "my_github_username"
       }
    }
  }
}
```

{% endcode %}

### Bugs

Users can come across an issue in your app. Provide them with a bug URL, so they can quickly share their findings with you. An object with a property `url` that contains a link to your public bug/issue tracker.

{% code title="/.homeycompose/app.json" %}

```jsonc
{
  "id": "com.athom.example",
  // ...
  "bugs": {
    "url": "https://bitbucket.org/athom/com.athom.myapp/issues"
  }
}
```

{% endcode %}

### Homey Community Topic

The [Homey Community](https://community.athom.com/) is a great place to share additional information about your app with your users and fellow developers. When the ID of the topic is provided, this shows a link on the App Store. You can get the ID from the topic's URL.

{% code title="/.homeycompose/app.json" %}

```jsonc
{
  "id": "com.athom.example",
  // ...
  "homeyCommunityTopicId": 1234
}
```

{% endcode %}

### Source

If you would like to, you can add a link to your source code to allow others to view your code and maybe even submit a Pull Request. A string, starting with `https://`.

{% code title="/.homeycompose/app.json" %}

```jsonc
{
  "id": "com.athom.example",
  // ...
  "source": "https://github.com/athombv/com.athom.myapp"
}
```

{% endcode %}

### Homepage

Share your company, brand or personal page with users to give them some more insight. A string, starting with `https://`.

{% code title="/.homeycompose/app.json" %}

```jsonc
{
  "id": "com.athom.example",
  // ...
  "homepage": "https://homey.app"
}
```

{% endcode %}

### Support

Sometimes your users need some help or might have some questions about your app. Consider offering them support, just in case they need it. Add a URL or e-mail address to the app manifest. A support URL is mandatory for Verified Developers. A string, starting with `https://` or `mailto:`.

{% code title="/.homeycompose/app.json" %}

```jsonc
{
  "id": "com.athom.example",
  // ...
  "support": "mailto:support@homey.app"
}
```

{% endcode %}