Building and Shipping Plugins

Active development / In-tree build

During development however, the workflow of 1. building the plugins outside of the project; 2. copying to a plugins folder; 3. running Headlamp pointing to that folder, is not a great development user-experience.

While we are planning a smarter way to develop plugins outside of the project’s tree and having them automatically built and served to the frontend, we have to use the work around of developing/testing them within the project (before building and shipping them externally once ready).

For that, you can develop your plugins inside the frontend/src/plugin/plugins folder. E.g. if your plugin is called MyPlugin, then your plugin structure should be as follows:

frontend/src/plugin/plugins/MyPlugin/index.tsx

Out-of-tree build

Once your plugin is working as intended, it should be compiled our of the Headlamp project. The index.tsx (or other Typescript/Javascript extensions) should be in its own module like:

MyPlugin/
  src/
    index.tsx
  package.json

Feel free to use npm create for getting the base structure/files right.

For helping with compiling the plugin code we have the @kinvolk/headlamp-plugin , which should be installed as a dev dependency:

npm install --save-dev @kinvolk/headlamp-plugin

Once that’s done, simply change your scripts element to use the headlamp-plugin script:

"scripts": {
  "build": "headlamp-plugin"
}

This way, when you run npm run build, the plugin will be compiled to a file within the module called dist/main.js

Shipping / Deploying Plugins

Once we have the plugin or plugins compiled, they should be included in Headlamp by having them in a “plugins directory” which should be passed to Headlamp’s server.

For example, if we have compiled 3 plugins called MyPlugin1, MyPlugin2, and MyPlugin3, they should be added to a directory in the following structure:

plugins/
  MyPlugin1/
    main.js
  MyPlugin2/
    main.js
  MyPlugin3/
    main.js

Then, when running Headlamp’s server, the -plugin-dir option should point to the directory:

./server -plugins-dir=/path/to/plugins/