Skip to main content

Setup Guide for plugin developers

Guide for how the plugin developer sets up its dev environment.

Code Editor

Install

Access to the @pexip/plugin-api package

  • Available via npm here

Pexip deployment settings

Since plugins are rendered as iframes, browser security settings need to allow this. The browser is instructed via various HTTP security headers on what behaviour is allowed for a given application.

Starting with version 32, Pexip deployments are configured to allow plugins hosted on the same host as the webapp (e.g.: from a custom branding package that has been uploaded to Infinity). For Infinity versions 31 or earlier, the default behaviour was to not allow iframes to be loaded by any webapps.

Enabling plugins hosted on external origins​

The default Infinity HTTP Content-Security-Policy (CSP) header blocks loading iframes from external origins by using the frame-src directive. To allow plugins from external origins (e.g.: localhost for plugin development) to be loaded, the frame-src directive needs to include the origins that iframes are permitted to be loaded from (e.g.: http://localhost:*).

Go to https://${managementNode}

-> Security -> HTTP Content Security Policy and add the external origins to the frame-src. 'self' is included in the frame-src directive by default as this allows plugins that have been included via branding packages to work, we recommend not removing this value unless there is a good reason to. For futher help on configuring frame-src, see the MDN documentation.

Enabling plugins on Infinity versions 31 or earlier​

Infinity versions 31 and earlier set X-Frame-Options to DENY. This means that plugins hosted via custom Infinity branding cannot be loaded. In order to allow plugins to be loaded, customers will need to run the security wizard and set Enable X-Frame-Options: DENY to off.

Running the example plugin

Build & add the plugin to the branding manifest​

  • Download the plugin-example zip below and unzip it. This example project will be a starting point for your plugin.

  • Install the project dependencies by running yarn from the root of the plugin-example folder

  • Run yarn build from the root of the plugin-example folder. This should create a dist folder with the following structure:

    |-- dist
      |-- assets
        index.js
      index.html

  • Take the contents of the dist folder and put it in a directory specific for the plugin, within the branding directory. For example:

    |-- branding
      |-- plugins
        |-- example-plugin
          |-- assets
            index.js
          index.html
      manifest.json

  • Reference the plugin in the branding manifest: "plugins": [{"src": "./<path-to-your-plugin>/index.html"}]

  • Verify that webapp3 is correctly picking up the plugin.

Verify that your plugin is running

Serve the plugin locally​

Sometimes, in the process of actively developing a plugin, you might find it easier to serve the plugin locally instead.

  • Install the project dependencies by running yarn from the root of the plugin-example folder

  • Run yarn start from the root of the plugin-example folder

  • Verify that the plugin is running on http://localhost:5173

  • Allow your webapp to render plugins from localhost as described here

  • Reference the plugin in the branding manifest: "plugins": [{"src": "http://localhost:5173"}]

Instead of building the plugin every time you make a change, you can simply refresh webapp3 and the latest plugin code will be loaded.

Plugin example

plugin-example.zip