App Package Overview

An app package is the main unit for delivering custom functionality to YouTrack. It can contain one module or combine UI, automation, endpoints, configuration, and app-owned data.

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 Data and Configuration

Apps can store local frontend state, work with ordinary YouTrack entities, and declare app-owned backend data. Choose a mechanism based on who needs the value, how long it must persist, and whether it contains a secret.

Mechanism	Scope and use	Important constraints
`host.storage`	Local UI state and caches shared by widgets from the same app in one browser.	Stores string keys and values asynchronously, with a 1 MB quota per app. It isn't tied to a YouTrack user account and isn't suitable for secrets or permission-protected data.
YouTrack entities	Issues, articles, projects, users, and other supported entities.	Access goes through the REST API or YouTrack JavaScript API and remains subject to the applicable permissions.
Extension properties	App-owned mutable data associated with a supported YouTrack entity.	The app must declare each property in `entity-extensions.json` and access it through `extensionProperties`.
App global storage	App-owned mutable data that isn't associated with a regular YouTrack entity.	Declared as properties of `AppGlobalStorage` and accessed through `ctx.globalStorage.extensionProperties`.
App settings	Administrator-provided global or project-level configuration, including credentials.	Declared in `settings.json` and accessed through `ctx.settings`. Store secret values in secret settings, not extension properties.

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 add custom UI to YouTrack, you can create widgets. You can embed a widget in several supported locations in the YouTrack UI. For the complete list, see Extension Points for Widgets.

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

Each backend JavaScript file in an app is classified by the object it exports:

Export	Module
`exports.rule` or `exports.stateMachine`	A workflow rule that automates YouTrack behavior.
`exports.httpHandler`	An HTTP handler that provides app endpoints.
`exports.aiTool`	A custom MCP tool.
No recognized module export	A utility module imported by another backend file.

Store each backend module in a separate .js file. Workflow rules in an app use the same rule constructors and JavaScript API as rules in a pure workflow.

For app-specific backend reference, see App Reference. For the shared backend API, see YouTrack JavaScript API.

10 September 2026