App Package Overview

This page provides an overview of an app package and its components.

App Package

Here is the file structure of a sample app package:

Here are the key components of the package:

The app manifest, a JSON file that is stored at the root level of the app package.
The custom schema for the app settings.
The definition for any extension properties used to store custom values for core YouTrack entities.
A widgets folder that contains subfolders for each widget.
The subfolder for an admin widget. This subfolder contains the index.html file and other supplementary files that are used by this widget.
A JavaScript file that contains the script for an additional module.

App Manifest

Each app package must include a manifest.json file at the root of the package directory. The manifest file provides general information about the app, such as the title, description, and the list of modules that this app includes.

To learn more about app manifests, see App Manifest.

App Settings

As an app developer, you have the option to provide a schema of custom settings for your app. The setting schema is described in a settings.json file. These settings are then accessible for configuration on the Settings tab of the app.

To learn more about custom settings for your app, see App Settings.

Extension Properties

Apps can extend core YouTrack entities with custom properties. We refer to these as extension properties. With extension properties, you can store custom values for core YouTrack entities. An app can then work with these custom properties and their values in its JavaScript-based modules.

Extension properties are declared in a dedicated file named entity-extensions.json. To define custom extension properties, add this file to the root level of the app package and declare each property inside the file.

To learn more, see Extension Properties.

Widgets

To modify the appearance of YouTrack and develop your own extensions to the YouTrack UI, you can create widgets. You can embed your widget in several extension points in the YouTrack UI. For the complete list of these extension points, see Extension Points.

Here you can see an example of a widget as described in the manifest:

{ "name": "Sample Widget", "key": "sample-widget", "indexPath": "index.html", "place": "ISSUE_FIELD_PANEL_FIRST", "description": "Optional widget description", "iconPath": "icon.png" }

Here you can see a sample index.html file containing the source code for this widget:

<!doctype html> <html> <head> <link rel="stylesheet" href="../index.css"> </head> <body class="plugin" style="padding: 0; overflow: hidden;"> <img src="logo.jpeg" style="width: 100%; height: 100%; object-fit: cover;"/> <script type="module"> const host = await YTApp.register(); </script> </body> </html>

JavaScript Modules

You can add various JavaScript-based modules to your app: custom HTTP handlers, workflow rules, import scripts, and SLA rules. To learn more about JavaScript modules for apps, see App Reference.

You must store the source code for each module in a separate .js file.

21 March 2025