Skip to main content

Headlamp Plugin Development Setup

Purpose: For contributors, shows how to set up the Headlamp plugin development environment.

What you'll have at the end​

A running Headlamp development server with hot-reload, where you can develop and test plugins locally.

Prerequisites​

  • Node.js >= 20.0.0
  • pnpm >= 9.0.0 (the repo pins pnpm@9.15.4 via packageManager in package.json)
  • A Kubernetes cluster with a valid kubeconfig (for testing plugins against a real cluster)

Step 1: Install dependencies​

cd headlamp-branding-plugin
pnpm install

pnpm reads pnpm-workspace.yaml and installs dependencies for all plugins under plugins/*.

Step 2: Start the development server​

# All plugins
pnpm run dev

# Or target a specific plugin
pnpm --filter @opencenter/headlamp-plugin-branding run dev

This starts webpack in watch mode. Changes to source files trigger automatic rebuilds.

Step 3: Run tests​

# All plugins
pnpm test

# Specific plugin
pnpm --filter @opencenter/headlamp-plugin-branding test

Tests use Jest. Test files live in plugins/<name>/__tests__/.

Step 4: Lint and format​

# Lint
pnpm run lint

# Format
pnpm run format

# Check formatting without writing
pnpm run format:check

Step 5: Build for production​

pnpm run build

Production bundles are written to plugins/<name>/dist/.

Check your work​

After completing setup, confirm:

pnpm run build          # All plugins build
pnpm test               # All tests pass
pnpm run lint           # No lint errors
pnpm run format:check   # Formatting clean

Troubleshooting​

SymptomFix
pnpm install failsClear cache: pnpm store prune, delete node_modules and pnpm-lock.yaml, then pnpm install
Plugin not found by workspace commandsVerify pnpm-workspace.yaml contains plugins/*
TypeScript errors in IDE but not in buildRestart the TypeScript language server; ensure tsconfig.json is correct

Next steps​