Adding a Headlamp Plugin

Purpose: For contributors, shows how to add a new Headlamp plugin to the monorepo.

Prerequisites

• Node.js >= 20.0.0
• pnpm >= 9.0.0
• The headlamp-branding-plugin repo cloned and dependencies installed (pnpm install)
• Familiarity with React 18 and the Headlamp plugin API

Steps

1. Create the plugin directory

All plugins live under plugins/ in the monorepo. The pnpm-workspace.yaml already includes plugins/*, so any new directory is automatically part of the workspace.

mkdir -p plugins/my-feature/src plugins/my-feature/__tests__ plugins/my-feature/assets

2. Add a package.json

Create plugins/my-feature/package.json:

{
  "name": "@opencenter/headlamp-plugin-my-feature",
  "version": "1.0.0",
  "main": "dist/main.js",
  "scripts": {
    "dev": "webpack --mode development --watch",
    "build": "webpack --mode production",
    "test": "jest",
    "lint": "eslint src --ext .ts,.tsx",
    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
    "format:check": "prettier --check \"src/**/*.{ts,tsx}\""
  },
  "peerDependencies": {
    "@kinvolk/headlamp-plugin": "^0.13.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

Use the @opencenter/headlamp-plugin- prefix for all plugin package names. This keeps naming consistent with the existing @opencenter/headlamp-plugin-branding package.

3. Create the entry point

Create plugins/my-feature/src/index.tsx:

import { registerPluginSettings } from "@kinvolk/headlamp-plugin/lib";

// Register your plugin with Headlamp
registerPluginSettings("my-feature", {
  // Plugin configuration here
});

4. Add webpack and TypeScript configuration

Copy the webpack.config.js and tsconfig.json from plugins/branding/ as a starting point. Adjust the entry path if your source layout differs.

5. Install dependencies

From the repo root:

pnpm install

pnpm resolves the new plugin automatically because pnpm-workspace.yaml uses the plugins/* glob.

6. Develop and test

# Start dev server for your plugin only
pnpm --filter @opencenter/headlamp-plugin-my-feature run dev

# Run tests
pnpm --filter @opencenter/headlamp-plugin-my-feature test

# Lint
pnpm --filter @opencenter/headlamp-plugin-my-feature run lint

7. Add tests

Place Jest tests in plugins/my-feature/__tests__/. Follow the patterns in plugins/branding/__tests__/ for mocking Headlamp APIs.

Verification

After completing the steps above, confirm:

# Plugin builds without errors
pnpm --filter @opencenter/headlamp-plugin-my-feature run build

# All workspace commands still work
pnpm run build
pnpm test
pnpm run lint

Troubleshooting

Symptom	Cause	Fix
pnpm install doesn't find the new plugin	Plugin directory not under plugins/	Verify path matches the plugins/* glob in pnpm-workspace.yaml
Peer dependency warnings	Missing Headlamp SDK	Ensure @kinvolk/headlamp-plugin is listed as a peerDependency
Build fails with module resolution errors	Incorrect webpack config	Compare your webpack.config.js with the one in plugins/branding/