Skip to content

Local Development

Local Development

Clone from . The repo root package.json is the single entrypoint for all build/lint/test operations.

External Repos

External repos (separate GitHub orgs):

  • headlamp-k8s/plugins: Flux, Backstage, Inspektor Gadget, App Catalog, Trivy plugins
  • headlamp-k8s/headlamp-website: headlamp.dev docs and blog

Prerequisites

  • Go ≥ 1.21
  • Node.js ≥ 20.18.1 (npm included)
  • A working ~/.kube/config pointing at any cluster (kind works great)

Bootstrap the dev environment

git clone https://github.com/kubernetes-sigs/headlamp
cd headlamp

npm run backend:build

npm run backend:start
# listening on :4466, insecure — do not use in production

npm run frontend:start
# listening on :3000, proxies /api/* to :4466

Open http://localhost:3000.

Changes to frontend/src/ hot-reload instantly.

Changes to backend Go files require rebuilding: 

npm run backend:build
npm run backend:start

Available npm scripts

Script What it does

npm run backend:build Compile the Go binary to backend/headlamp-server npm run backend:start Run the backend in insecure dev mode npm run backend:lint golangci-lint (can auto-fix with :lint:fix) npm run backend:test Go unit tests npm run backend:coverage Coverage report to stdout npm run frontend:start Vite dev server with HMR npm run frontend:build Production SPA build npm run frontend:lint ESLint + TypeScript checks npm run frontend:test Jest unit tests npm run start:app Launch Electron desktop app locally Formatting and linting

npm run backend:format # gofmt + goimports npm run backend:lint:fix # auto-fix what golangci-lint can

npm run frontend:lint # ESLint

✓ tip

Run npm run backend:lint and npm run frontend:lint before every PR. CI will fail on lint errors. For Go, the project uses golangci-lint with a config in backend/.golangci.yml.