---
schema: rendered-html/v1
title: "App Package Overview | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/app-overview.html
generated_at: 2026-06-11T15:01:57.739817+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- Get Started with Apps
- App Quick Start Guide
- Apps FAQ
- Enhanced DX for TypeScript Apps
- YouTrack App Architecture
- [App Package Overview](app-overview.html)
- [App Manifest](jetbrains__com__help__youtrack__devportal__app-manifest.md)
- Widgets
- [App Settings](jetbrains__com__help__youtrack__devportal__app-settings.md)
- Extension Properties
- [App Permissions](jetbrains__com__help__youtrack__devportal__app-permissions.md)
- Authentication for Apps
- [App Visibility](jetbrains__com__help__youtrack__devportal__app-visibility.md)
- Global and Project Scopes
- Launch Checklist
- App Use Cases
- App Reference
- MCP Tools
- YouTrack Workflows
- YouTrack Import Scripts
- YouTrack Form API
- YouTrack REST API
- Hub REST API

1. Apps
2. Get Started with Apps
3. [App Package Overview](#0)

# App Package Overview﻿

Last modified: 07 May 2026

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

## App Package﻿

Here is the file structure of a sample app package:

[![An example of an app package](https://crawler.prototype.prolicht.digital/l/BQM7O6)](https://resources.jetbrains.com/help/img/youtrack/app-structure.png)

Here are the key components of the package:

- The [app manifest](/help/youtrack/devportal/app-overview.html#app-manifest), a JSON file that is stored at the root level of the app package.
- The custom [schema for the app settings](/help/youtrack/devportal/app-overview.html#app-settings).
- The definition for any [extension properties](/help/youtrack/devportal/app-overview.html#extension-properties) used to store custom values for core YouTrack entities.
- A `widgets` folder that contains subfolders for each [widget](/help/youtrack/devportal/app-overview.html#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](/help/youtrack/devportal/app-overview.html#app-javascript-modules).

## 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](jetbrains__com__help__youtrack__devportal__app-manifest.md).

## 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](jetbrains__com__help__youtrack__devportal__app-settings.md).

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

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.

- [App Package Overview](/help/youtrack/devportal/app-overview.html)
- [App Package](/help/youtrack/devportal/app-overview.html#app-package)
- [App Manifest](/help/youtrack/devportal/app-overview.html#app-manifest)
- [App Settings](/help/youtrack/devportal/app-overview.html#app-settings)
- [Extension Properties](/help/youtrack/devportal/app-overview.html#extension-properties)
- [Widgets](/help/youtrack/devportal/app-overview.html#app-widgets)
- [JavaScript Modules](/help/youtrack/devportal/app-overview.html#app-javascript-modules)

YouTrack App Architecture[App Manifest](jetbrains__com__help__youtrack__devportal__app-manifest.md)

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.
