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:


    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:


    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:


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

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