Skip to main content
Version: 26.1

Plugin UI development guide

The described approach covers the UI part of the plugin engine starting from ReportPortal version 24.1. It also reflects the organizations model: instance, organization, and project levels have separate layouts, sidebars, and settings.

To learn how to deal with ReportPortal plugins from the Backend side, follow the Plugin API development guide.

Start from the plugin template. Bundled UI (webpack, metadata.json, extension points) lives in ui/.

The concept​

The Service UI and Plugin UI are integrated at runtime using JavaScript and share common dependencies via Webpack Module Federation.

From Service UI side​

The ReportPortal Service UI (the core UI – further in the text) is built with React library and uses Redux for state management. It has a list with extension points that can be used to extend the core UI with custom React components come from plugins. Extension points are described here.

The context (e.g. current user, organization, project) from core UI is shared via Redux state and can be accessed in plugins. In addition to this, the core UI provides a set of common components and utils that can be used in plugins as well.

After uploading the plugin to the ReportPortal (see how) and opening the application in browser, the core UI will load the descriptors file (metadata.json) from plugin to define the extension points implemented there.

When the user opens a place that matches an extension point (e.g. organization or project settings), the core UI loads the React component from the Plugin UI files and render it in the appropriate place in application.

The plugin details page under Administrate → Plugins is built by the core UI, not by your plugin UI. To hide Add integration there, set isIntegrationsAllowed=false in the plugin manifest (gradle.properties).

metadata.json and webpack exposes​

Each UI extension is declared in ui/src/metadata.json and must match a webpack Module Federation exposes entry.

Typical fields:

FieldRole
scopeMust equal the webpack federation name (in the template: plugin_name). It is not the same as extensions[].name or package.json name.
extensions[].typeExtension point, prefixed with uiExtension: (for example uiExtension:settingsTab).
extensions[].nameTab / route key used by the host (for settings tabs this is the URL settingsTab segment). For projectPage, used as the URL segment if slug is omitted.
extensions[].moduleNameFederated module, for example ./projectSettingsTab. Must match exposes.
extensions[].titleOptional title shown in the host UI (settings tab label, sidebar label).
extensions[].slugOptional. For projectPage: this is the URL segment (.../plugin/(slug)/...). If omitted, the URL uses name.
extensions[].iconOptional. For projectPage: { "type": "svg", "content": "<svg ...>" }. If present, a project sidebar link is added. Only SVG is supported.
extensions[].menuOrderOptional. For projectPage: position of the sidebar item among other project sidebar links.
extensions[].iconNameOptional short id for sidebar click analytics (projectPage and organization sidebar).

Each exposed module must export default the root component: the core UI loads it with React.lazy, which expects a default export.

If a sidebar button navigates to a settings tab, its settingsTab payload must use the same name.

Optional top-level overrides.disablePluginPopupContent is a map of locale codes to body text for the “disable plugin” confirmation. Omit overrides to keep the host default wording.

Example (from the template; names like template are placeholders):

{
"scope": "plugin_name",
"extensions": [
{
"name": "template",
"type": "uiExtension:adminPage",
"title": "Template plugin — instance admin",
"moduleName": "./instanceAdminPage"
},
{
"name": "orgSettingsTemplate",
"type": "uiExtension:organizationSettingsTab",
"title": "Template plugin — organization settings",
"moduleName": "./organizationSettingsTab"
},
{
"name": "projectSettingsTemplate",
"type": "uiExtension:settingsTab",
"title": "Template plugin — project settings",
"moduleName": "./projectSettingsTab"
}
]
}

Shared libraries​

The core UI shares major dependencies via Webpack Module Federation. Plugins can reuse them without loading a second copy in the browser when versions are compatible. Keep shared / externals in the plugin webpack config aligned with the ReportPortal UI you target. redux is typically listed under webpack externals so the host supplies a single store.

Shared libraries from the core UI:

PackageNotes
reactSingleton
react-domSingleton
react-reduxSingleton
react-intlSingleton
redux-formSingleton
redux-first-routerRouting
@reportportal/ui-kitDesign system
react-trackingAnalytics
classnames
prop-types
moment
html-react-parserUsed for sidebar SVG icons
history
fast-deep-equal
react-copy-to-clipboard
react-dnd
react-dnd-html5-backend

Shared extension props​

After embedding into the core UI, each extension root receives components, selectors, actions, and utils via props (built in createImportProps and spread by FederatedExtensionLoader).

The full set is defined in createImportProps.js. In the plugin, you can type these props with the interfaces from the plugin template.

Typical groups: lib, components, componentLibrary, constants, actions, selectors, utils, validators, icons, HOCs, portalRootIds.

Organization-aware pieces injected for plugins include, among others:

  • selectors: urlOrganizationSlugSelector, urlProjectSlugSelector, urlOrganizationAndProjectSelector, activeOrganizationSelector, organizationIntegrationsSelector
  • constants: ORGANIZATION_SETTINGS_TAB_PAGE, ORGANIZATION_PROJECTS_PAGE, ORGANIZATIONS_PAGE, PLUGIN_UI_EXTENSION_ADMIN_PAGE, PROJECT_SETTINGS_TAB_PAGE

Call plugin API commands with utils.fetch and utils.URLS from these props. The template hook useCommandExecutor posts to pluginsCommandsCommon; PLUGIN_NAME must match pluginId in gradle.properties.

To open a host modal, dispatch actions.showModalAction (there is no separate uiExtension:modal type).

Extension points​

type in metadata.json. These are the points a custom plugin can use after upload. The plugin template covers the navigation and settings types.

Extension typeDescription
uiExtension:adminPageFull page at https://your_server/ui/#plugin/(pluginPage)/.... Pair with adminSidebarComponent for a sidebar link.
uiExtension:adminSidebarComponentItem in the instance sidebar.
uiExtension:organizationSettingsTabTab on organization settings: .../organizations/(organizationSlug)/settings/(tabName). name is the settingsTab segment. There is no org /plugin/... page.
uiExtension:organizationSidebarComponentItem in the organization sidebar. Does not open its own page; link it to a settings tab. Optional iconName for click analytics.
uiExtension:settingsTabTab on project settings: .../projects/(projectSlug)/settings/(tabName). name is the settingsTab segment.
uiExtension:sidebarComponentItem in the project sidebar. You render the control (for example SidebarButton).
uiExtension:projectPageFull page at .../projects/(projectSlug)/plugin/(pluginPage)/.... pluginPage is slug, or name if slug is omitted. Sidebar link only if an SVG icon is set (title, menuOrder, iconName).
uiExtension:launchItemComponentExtra content under each launch name on the Launches page (not on test items).
uiExtension:integrationFormFieldsFields in the integration create/edit modal (instance, organization, and project). Use IntegrationFormField from the core UI. The plugin must set isEmbedded=true in gradle.properties (details.metadata.embedded).
uiExtension:integrationSettingsIntegration details on instance, organization, and project Integrations. Use IntegrationSettings from the core UI. Same embedded requirement as above.

Other types (login, Unique Errors, Make Decision, Post issue, and similar) are for specialized plugins. Declaring them in metadata.json is not enough unless the plugin matches what core UI expects. Full list: constants.js.

Host SidebarButton expects icon as an SVG string (parsed with html-react-parser). In the template, import .svg files from ui/src/icons/ via svg-inline-loader.

To match ReportPortal sidebars:

  • Use width="48" height="40" and viewBox="0 0 48 40".
  • Prefer fill="currentColor" on shapes so hover/active colors apply.
  • Prefer path / rect / polygon over circle / ellipse for the active state (host CSS recolors those elements).

Localization​

Plugin translations are shipped in the plugin artifact and merged into ReportPortal at runtime. Declare them in metadata.json:

"localization": { "messages": "locale-{lang}.json" }

Without this section the plugin falls back to core strings and defaultMessage.

The template workflow mirrors Service UI: defineMessages in code → npm run manage:translations → committed ui/src/locales/{ru,uk,be,zh,es}.json → webpack copies them to locale-{lang}.json. Use a unique message id prefix (for example PluginTemplate.*); it does not have to equal pluginId.

Details can be found here.

Local development​

Preconditions: Node.js 20+.

Then run the commands from the plugin frontend directory (in the template this is ui/):

npm install
npm run dev # webpack watch
npm run start # serve built files (port 9090 in the template)

Option 1 — override in the browser console (resets on reload). Available from ReportPortal 24.1:

window.RP.overrideExtension('{pluginName}', 'http://localhost:9090');

Option 2 — webpack proxy in Service UI (survives reloads). In service-ui/app/webpack/dev.config.js, add before the existing /api/ rule:

{
context: ['/api/v1/plugin/public/{pluginName}/'],
target: 'http://localhost:9090',
changeOrigin: true,
pathRewrite: { '^/api/v1/plugin/public/{pluginName}/file': '' },
},

In both options, replace {pluginName} with pluginId from gradle.properties. Then restart the Service UI dev server if you used the proxy.

Build the UI source code: npm run build.