# 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:

![An example of an app package](https://resources.jetbrains.com.cn/help/img/youtrack/app-structure.png)

Here are the key components of the package:

* The [app manifest](#app-manifest), a JSON file that is stored at the root level of the app package.

* The custom [schema for the app settings](#app-settings).

* The definition for any [extension properties](#extension-properties) used to store custom values for core YouTrack entities.

* A `widgets` folder that contains subfolders for each [widget](#app-widgets).

* 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-javascript-modules).

## 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](apps-host-api.html#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](apps-extension-properties.html) | 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](apps-extension-properties.html#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](app-settings.html) | 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-manifest.html).

## 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](app-settings.html).

## 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](apps-extension-properties.html).

## 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](apps-reference-extension-points.html).

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

```JSON
{
    "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:

```HTML
<!doctype html>
<html>
    <head><link rel="canonical" href="https://www.jetbrains.com.cn/en-us/help/youtrack/devportal/app-overview.html.md/" data-react-helmet="true"/>
        <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](Workflow-Rules.html) that automates YouTrack behavior. |
| `exports.httpHandler` | An [HTTP handler](apps-reference-http-handlers.html) that provides app endpoints. |
| `exports.aiTool` | A [custom MCP tool](custom-ai-tools.html). |
| 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](apps-reference.html). For the shared backend API, see [YouTrack JavaScript API](Workflows-in-JavaScript.html).