Project: Headlamp (Observability and Analysis / Observability)
File: building.md

title: Building and Shipping Plugins linktitle: Building & Shipping This section explains how to start developing a Headlamp plugin, and how to ship it once finished. This is how to start a new plugin: ```bash npx --yes @kinvolk/headlamp-plugin create headlamp-myfancy cd headlamp-myfancy npm run start ``` There's some basic code inside src/index.tsx. Now run Headlamp (the desktop app or the ), and your plugin should be loaded. Using the above commands means that Headlamp will automatically reload whenever to make a change to the plugin. This automatic reload does not happen when running in-cluster, even if the plugins folder is changed. i.e. if you want to serve updated plugins, you need to restart the server. Your plugin has a few tools built in to help make development easier. ```bash npm run format ``` ```bash npm run lint ``` Eslint also allows you to try and automatically fix issues. ```bash npm run lint-fix ``` ```bash npm run tsc ``` ```bash npm run test ``` To build the previous plugin example for production, run the following command: ```bash cd headlamp-myfancy npm run build ``` This will create a file with the bundled plugin in `headlamp-myfancy/dist/main.js`. For convienience the `headlamp-plugin build` command can build a package or folder of packages. ```bash npx @kinvolk/headlamp-plugin build myplugins/headlamp-myfancy npx @kinvolk/headlamp-plugin build myplugins ``` Once a plugin is ready to be shipped (built for production) it needs to be placed in a "plugins directory", for Headlamp to load them. For example, if we have built 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 ``` If our plugins are places in `myplugins`, we can conveniently create that folder with the following command: ```bash npx @kinvolk/headlamp-plugin extract ./myplugins /path/to/.plugins ``` This also works individually (for each plugin): ```bash npx @kinvolk/headlamp-plugin extract ./myplugins/MyPlugin1 /path/to/./plugins ``` For in-cluster Headlamp deployments, when running Headlamp's server, the `-plugin-dir` option should point to the directory: ```bash ./headlamp-server -plugins-dir=.plugins ``` The Headlamp desktop app will look for the plugins directory (in the format mentioned above) either under the user's Headlamp configuration folder, or within the current folder as `.plugins` if the former doesn't exist. To build a Headlamp app with a set of plugins, first extract some plugins into the .plugins folder in the root of the "headlamp" repo. ```bash cd plugins/examples/pod-counter npm install npm run build cd ../.. mkdir .plugins npx @kinvolk/headlamp-plugin extract ./plugins/examples/ ./.plugins ls -la .plugins make app-linux ``` For more on how to extract files into there see "Shipping and Deploying Plugins"

See the blog post "" for more information on building a container image with your plugins. What is a storybook story? From https://storybook.js.org/docs/web-components/get-started/introduction Storybook is a tool for UI development. It makes development faster and easier by isolating components. This allows you to work on one component at a time. You can develop entire UIs without needing to start up a complex dev stack, force certain data into your database, or navigate around your application. See an example in your browser: ```bash $ cd plugins/examples/pod-counter $ ls src headlamp-plugin.d.ts index.tsx Message.stories.tsx Message.tsx $ npm install $ npm run storybook ``` Your browser should open and show you a Message component with three different states the component can be in. Notices that there is a Message.stories.tsx to go along with the Message.tsx which has the `<Message>` component defined within it. See that file for an example of how to write a story. Another benefit of writing storybook stories is that they can act as unit tests for regression testing. With storyshots it will save snapshots of html for the different states that a component can be in. See the guide in the storybook documentation for more information. This is in addition to the benefit of making sure your components can be manually tested and developed quickly in isolation. See the for full details on storybook. A workflow for testing your plugin on github with actions. Below is based on the docs from GitHub. Place this in a file named something like `.github/workflows/headlamp-plugin-github-workflow.yaml` in the root of your repo. ```yaml name: Headlamp plugin linting, type checking, and testing on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest defaults: run: working-directory: ./your-folder-of-plugins strategy: matrix: node-version: [18.x] steps: uses: actions/checkout@v4 name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@v3 with: node-version: ${{ matrix.node-version }} run: npx @kinvolk/headlamp-plugin lint . run: npx @kinvolk/headlamp-plugin format --check . run: npx @kinvolk/headlamp-plugin tsc . run: npx @kinvolk/headlamp-plugin test . run: npx @kinvolk/headlamp-plugin build . ``` Please see the github documentation for further details on workflows and actions. There's a command which handles much of upgrading plugins to the latest headlamp-plugin version. This upgrade command also audits packages, formats code, lints and type checks. Additionally this handles some code changes needed for plugins. For example, it handles running the material-ui 4 to mui 5 'codemod' code changes, and creates missing configuration added in different versions of headlamp-plugin. Testing is necessary after running the upgrade command. Of course make sure you have a backup of your plugin folder before running it. ```bash npx @kinvolk/headlamp-plugin upgrade --headlamp-plugin-version=latest your-plugin-folder ```