Skip to main content

Check out Port for yourself ➜ 

Plugins

A plugin is a self-contained web UI, built from HTML, JavaScript, or a framework such as React, that you develop locally and upload to Port. Plugins power custom widgets that render inside dashboards and entity pages using the same catalog data and permissions as the rest of the platform.

You develop and build the plugin in your usual toolchain (for example VS Code, Cursor, or WebStorm), then upload a single compiled HTML file. Port hosts that file for you, there is no separate infrastructure to run. When a custom widget renders, Port serves the plugin, injects authentication, and passes context such as entity data, dashboard filters, page context, and user identity, so your code can call Port APIs safely.

Administrators upload, list, update, and delete plugins using the Port plugins CLI. You can define custom parameters (Params), those fields appear when someone creates or edits a custom widget, which lets a single plugin power different widgets. For example, different blueprints or date properties for a shared calendar-style UI.

Example plugin​

Use the port-plugin-sample repository on GitHub as a starting point. It shows a minimal plugin built with React and TypeScript.

The sample receives context from the Port host through postMessage (user, page, params, and entity). It requests a JWT and API base URL from the host, then uses those to call the Port API.

The production build outputs a single self-contained ui.html file with inlined JavaScript and CSS, which you can upload with the Port plugins CLI.

Port plugins CLI​

The Port plugins CLI (@port-labs/port-plugins-cli) uploads and manages plugins from your terminal or from CI.

Install the CLI:

npm install -g @port-labs/port-plugins-cli

For full install steps, commands, authentication, configuration, and plugin metadata limits, see the @port-labs/port-plugins-cli package on npm.

Admin access

Authenticate the Port plugins CLI with a client ID and client secret, or with an access token. Admin permissions are required to upload and manage plugins. For where to find your credentials, see Find your Port credentials

Plugins manager​

Once a plugin is uploaded, admins can manage it directly within the Builder interface:

  1. Navigate to the Builder page.
  2. Click on the Plugins Manager in the left sidebar to manage your uploaded plugins.

The Plugins Manager lists all plugins uploaded to your organization, showing each plugin's identifier, title, description, size, creator, and the custom parameters it exposes (Params). From here, admins can review available plugins before wiring one into a custom widget.

To use a plugin in a dashboard or entity page, see Custom widgets.

Custom widget​

Custom widgets let you run your own plugin's UI directly inside Port dashboards and entity pages. A plugin is a self-contained HTML file, write it in your IDE, build it, and upload it to Port using the Port plugins CLI. Uploaded plugins are listed in the Plugins Manager. For details, see Plugins.

Organization plugins only

Only plugins uploaded to your organization are listed in the Plugins Manager and available when you create a custom widget. Upload them with the Port plugins CLI.

Why use custom widgets?​

When built-in widgets aren't enough - a deployment calendar, an incident timeline, a production readiness panel - custom widgets let you bring those interfaces directly into Port, leveraging Port's hosting, authentication, secured environment, and rich context.

Widget properties​

FieldTypeDescriptionDefaultRequired
TitlestringCustom widget title.—true
IconstringCustom widget icon.—false
DescriptionstringCustom widget description.—false
Plugin IdstringThe plugin to display. Choose from your organization's uploaded plugins.—true
Param ValuesobjectKey-value pairs for the plugin's custom parameters. Each parameter has a type (string, number, boolean, object, array, or blueprint) and a value. Which parameters are required is defined by the plugin's configuration.—false
Blueprint parameters

For blueprint type parameters, use the blueprint's identifier as the value.

UI preview​

When creating or editing a custom widget, Port renders a live preview using the real widget context, so you can see how the widget will look before saving.

Local development toggle

You can turn on the toggle in the preview section to use development mode. When enabled, it overrides the plugin URL and postMessage URL to localhost:9000 so you can develop and test your plugin locally.

Please note: In development mode, CORS prevents the plugin from sending browser requests to the API.

How Port communicates with your plugin​

The widget communicates with the plugin via postMessage. Port provides two mechanisms to inject context into the plugin:

Port token​

Listen for the PORT_TOKEN event to receive an authenticated token for making Port API calls from within the widget:

Plugin data​

Port sends context to the plugin via the PLUGIN_DATA event. The payload includes:

  • User – the logged-in user's data.
  • Page – the page identifier and any filters applied on the page (identifier, pageFilters).
  • Entity – on entity pages, an object containing the current entity's data.
  • Params – the parameter values configured for the widget.
  • Base Url - port's url for making Port API calls in the plugin

Using Terraform​

To add a custom widget with Terraform, include a widget object with type set to custom-widget in the widgets configuration. See Port's Terraform provider for how to pass widget definitions on your page resource.

Example:

{
  "icon": "<YOUR_ICON>",
  "pluginId": "<YOUR_PLUGIN_ID>",
  "title": "<YOUR_WIDGET_TITLE>",
  "description": "<YOUR_DESCRIPTION>",
  "paramValues": {
    "<PARAM_NAME>": {
      "value": <PARAM_VALUE>,
      "type": "<PARAM_TYPE>"
    }
  },
  "type": "custom-widget",
  "id": "<YOUR_WIDGET_ID>"
}
required fields

pluginId, title, type, and id are required (type must be custom-widget).

API reference​

Use these Port API endpoints to upload, list, update, and delete plugins programmatically: