Setup Guide for plugin developers
Guide for how the plugin developer sets up its dev environment.
Code Editor
- Download a code editor, e.g. Visual Studio Code
Install
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 theplugin-example
folderRun
yarn build
from the root of theplugin-example
folder. This should create adist
folder with the following structure:|-- dist
|-- assets
index.js
index.htmlTake 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.jsonReference the plugin in the branding manifest:
"plugins": [{"src": "./<path-to-your-plugin>/index.html"}]
Verify that webapp3 is correctly picking up the plugin.
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 theplugin-example
folderRun
yarn start
from the root of theplugin-example
folderVerify that the plugin is running on http://localhost:5173
Allow your webapp to render plugins from
localhost
as described hereReference 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