Developer Portal for YouTrack and Hub Help

Test a Custom Widget

The Custom Widgets page contains a link to the Widgets Playground page. The widgets playground lets you preview and test your widgets while they are in development.

This page basically lets you load your widget in a sandbox environment.

Load a Custom Widget in the Widgets Playground

To test your widget, you need to load it in the widgets playground.

To load your widget in the widgets playground:

  1. First, upload your widget to a development server.

    You can use any server software that hosts static files, like webpack. If you use this option, the development server must provide a special header that gives the widgets playground access to load the content. This header is set in the webpack-config for the webpack-dev-server. For example:

    devServer: { headers: { 'Access-Control-Allow-Origin': '*' } },

    You can also run a static server on a local directory using npm http-server (requires Node.js). For example, the following command installs the http-server globally and serves the content that is stored in the widget-folder directory on port 9002.

    npm install http-server -g http-server ./widget-folder --cors -c-1 -p 9002

    You can then load the widget into the widgets playground from the http://localhost:9002/ address.

    Whichever option you use, you will need to serve the widget over HTTPS. For more information, see Testing Widgets over a Secure Connection.

  2. Open the widgets playground page.

    • From the Administration menu, select Server Settings > Custom Widgets.

    • Click the Widgets playground link.

  3. Enter the web address for your custom widget in the input field.

  4. Click the Load widget button.

    • The widget is loaded and displayed in the widgets playground.

      Widget playground

If you modify the code and upload these changes to your web server, use the Reload widget button to refresh the widget content and test the updates.

Testing Widgets over a Secure Connection

To load your custom widget in the widgets playground, the development server that you use to serve the widget should be available over HTTPS. This is a security requirement for all modern web browsers.

If you're working with YouTrack Cloud, your browser will also block any attempts to establish an unsecured connection with your instance.

Consider the following options:

  • If you use webpack, you can pass the --https option in the command that you use to run the development server. The server will have self-signed certificate, so you might need to add it to the list of trusted certificates on your local machine. For more information, refer to the webpack documentation.

  • You can expose your local server to the internet over HTTPS with a valid SSL certificate using ngrok or a similar tunneling reverse-proxy. To run ngrok, refer to the download and installation instructions for your operating system.

    The following example shows you how to run the development server and expose it to the web for macOS and Linux:

    # Run your dev server, for example: http-server ./widget-folder --cors -c-1 -p 9002 # Expose this port ngrok http 9002

    The ngrok service generates a secure public URL that you can use to load your widget in the widgets playground page.

Last modified: 19 June 2024