Widget Development Guide
Custom widgets are miniature application views that can you can embed in a YouTrack dashboard. You can build a widget that lets you view and interact with any application that is part of your software ecosystem, including custom views for YouTrack data and information that is stored in your built-in Hub service.
This page includes a basic overview of the widget package and manifest file. For a step-by-step introduction to custom widgets, read the Custom Widget Tutorial.
The fastest way to build a custom widget is to use our Yeoman generator. When you run the generator:
Yeoman builds the basic project structure and installs all the required dependencies.
index.htmlfile that is required for the widget package is created in the
The prompts in the command line let you specify values for the
authorattributes in the
The code for a sample widget is saved to the
To build a custom widget with the generator, access the widget generator in GitHub and follow the instructions in the README file. To get started, use the following commands:
Then switch to the root directory of your widget (create one if necessary) and run:
The generator prompts you to enter the widget name (defaults to the name of the current directory), widget description, and author. Yeoman creates your project files and installs all the dependencies for you.
At this point, you should have all the tools you need to get started. As you build your widget, use the information on this page for reference.
The widget must have entry file that is named
Your widget package can contain related source files.
There are a few resources that you can use to build your widgets.
This .css file contains the default text styles and layout definitions that are used for widgets in YouTrack. You can use this as the default stylesheet for your dashboard widgets or modify these style to change your widget layout.
This script contains code that communicates with a dashboard through messages. It creates a
To use this script, choose one of the following implementations:
JetBrains has published an open-source library of web components that are used for our web-based products. The library contains over 50 React controls, ranging from simple links and buttons to sophisticated controls like a date picker and an interactive hierarchical data list. This library is used extensively inside YouTrack, Hub, Upsource, TeamCity and other products.
For a complete list of components and setup instructions, access the Ring UI library online.
When you have assembled all of the content and source files for your widget, add a manifest to the top-most directory and create a ZIP archive. You can then import the ZIP archive into YouTrack and enable the widget for use on your dashboards.
Each widget should contain a
manifest.json file. This file defines the attributes for your custom widget.
For YouTrack to read and display the attributes in the widget manifest:
The file must be named
The file must be stored in the top-most directory of the ZIP archive.
The following attributes are defined in the widget manifest:
The internal ID that is used to identify the widget in YouTrack. This ID must be unique per server.
The version number of the widget app.
The name of the custom widget. This identifies the widget in the Custom Widgets list and is shown in the Add widget drop-down menu.
The description that is displayed on the Custom Widgets list.
The name and email address of the developer who created the widget. Specified in the same format that is used in an NPM package. For more information, refer to the npm package description.
The web address of the widget homepage or code repository. Shown in the Details sidebar in the widget list.
The name of the application that the widget is designed to display content from. For example,
The address of the image that is used as the widget icon. The location is relative to the widget root folder, without a leading slash. If empty, the icon of the application referenced in the
A list of services to which the widget sends HTTP requests. Specified as a sequence of key and value pairs. For the widget to work as expected, these services must be connected to your YouTrack installation. For more information, see Dependencies.
A list of products and compatible versions where the widget can be installed. Specified as a sequence of key and value pairs, similar to the list of dependencies. For more information, see Products.
A list of visual attributes. The following attributes are supported:
The values that can be specified for the
A list of capabilities that the widget supports in the web browser. These attributes inform users who install the widget of functionality that manipulates browser behavior. The following attributes are supported:
The following example shows how each of these attributes are defined in the JSON file. To build your own manifest, copy this example, paste it into your editor, and replace the sample attributes with your own.
There are two sections in the widget manifest that define whether the widget is compatible with an installation and the services that are connected to it. Use the information provided here to set the values in your manifest accordingly.
dependencies section contains a list of services to which the widget sends HTTP requests. If these services are not connected to the YouTrack installation, the widget does not have any data to display.
In some cases, your HTTP requests require a specific API version for the connected service. To function properly, your widget needs to specify the minimum version number that supports the request.
products section lists the products into which the widget can be installed. Here, the versioning depends on the version of the dashboard API that is supported by the product itself.
Extensions to the dashboard API are officially supported in new minor versions of Hub. New minor versions of YouTrack and Upsource incorporate these changes as well.
For example, if a widget uses a method that was added after the release of Hub 2018.1, the widget can be installed in Hub versions 2018.2 and later. The references to YouTrack and Upsource in the
products section should also require 2081.2 as the minimum version for installation.
To protect your installation against malicious archive packages, Hub blocks uploads that are too large or contain too many files. These limitations apply to all uploads, including custom widgets that have been downloaded from JetBrains Marketplace. Each widget package is subject to the following limitations:
The ZIP archive itself cannot be larger than 10 MB.
Single uncompressed files inside the archive cannot be larger than 30 MB.
The ZIP archive cannot contain more than 1000 files.