headlamp-plugin-template/README.md

Headlamp Plugin Template

A starter template for building Headlamp plugins — Kubernetes UI extensions that run inside the Headlamp desktop or web application.

What this is

This repository is a GitHub template that gives you a working Headlamp plugin skeleton with:

• A sidebar entry and route registered via the Headlamp SDK
• A placeholder resource list component ready to be swapped for your CRD view
• Vitest + React Testing Library test setup
• ESLint + Prettier configured via @kinvolk/headlamp-plugin
• CI workflow (lint, typecheck, test) and a manual release workflow
• ArtifactHub metadata files for publishing your plugin
• Renovate for automated dependency updates

Getting Started

1. Create your repo from this template

Click the "Use this template" button at the top of this page on GitHub, then create a new repository under your org.

2. Rename the placeholder values

Search the repo for YOUR_ORG, YOUR_REPO, and YOUR_NAME and replace them with your actual values. Key files to update:

File	What to change
package.json	name, author, repository, bugs, homepage
artifacthub-pkg.yml	name, displayName, description, homeURL, annotations
artifacthub-repo.yml	repositoryID (after registering), owners

3. Install dependencies and start developing

npm install
npm start

npm start runs headlamp-plugin start which launches a local dev server. Open Headlamp (desktop or http://localhost:4466) and load the plugin from http://localhost:4466.

To point Headlamp at your dev server, set the HEADLAMP_PLUGIN_URL in your Headlamp config or use the in-app plugin manager to add http://localhost:4466.

Project Structure

.
├── src/
│   ├── index.tsx                        # Plugin entry point — registers sidebar entries and routes
│   └── components/
│       ├── ResourceListPage.tsx         # Placeholder list view — replace with your CRD UI
│       └── ResourceListPage.test.tsx    # Tests for the list view
├── .github/
│   └── workflows/
│       ├── ci.yaml                      # Lint, typecheck, test on every push/PR
│       └── release.yaml                 # Manual release workflow (builds + publishes artifact)
├── artifacthub-pkg.yml                  # ArtifactHub package metadata
├── artifacthub-repo.yml                 # ArtifactHub repository metadata
├── renovate.json                        # Automated dependency updates via Mend Renovate
├── tsconfig.json                        # TypeScript config (extends headlamp-plugin base)
├── vitest.config.mts                    # Vitest configuration
└── vitest.setup.ts                      # Test setup (jest-dom + localStorage shim)

Building your plugin

Adding a CRD list view

The recommended approach uses the Headlamp SDK's K8s.makeKubeObject helper:

import { K8s } from '@kinvolk/headlamp-plugin/lib';

// 1. Define your CRD type
interface MyResourceSpec {
  someField: string;
}

// 2. Create a typed resource class
const MyResource = K8s.makeKubeObject<MyResourceSpec>('MyResource');
MyResource.apiEndpoint = K8s.ApiProxy.apiFactory('your.group.io', 'v1', 'yourresources');

// 3. Use it in a component
function MyResourceList() {
  const [resources, error] = MyResource.useList();
  // ...
}

Replace the contents of src/components/ResourceListPage.tsx with your real list view, then update src/index.tsx if you need additional routes or sidebar entries.

Common SDK imports

import {
  registerRoute,
  registerSidebarEntry,
  registerDetailsViewSection,
} from '@kinvolk/headlamp-plugin/lib';

import {
  SectionBox,
  SectionHeader,
  NameValueTable,
  Loader,
  StatusLabel,
} from '@kinvolk/headlamp-plugin/lib/CommonComponents';

Full API reference: https://headlamp-k8s.github.io/headlamp/

Testing

Run the test suite:

npm test

Run in watch mode during development:

npm run test:watch

Tests use Vitest with React Testing Library. The jsdom environment is configured in vitest.config.mts. Mock @kinvolk/headlamp-plugin/lib/CommonComponents in your test files using vi.mock — see ResourceListPage.test.tsx for the pattern.

Packaging for ArtifactHub

After your first release:

1. Update artifacthub-pkg.yml:

   • Set version and appVersion to the released version
   • Update annotations.headlamp/plugin/archive-url to point to the release artifact URL
   • Compute the SHA-256 checksum of the .tar.gz artifact and set annotations.headlamp/plugin/archive-checksum

2. Register your repository on ArtifactHub and paste the repositoryID into artifacthub-repo.yml.

3. ArtifactHub will automatically pick up new versions when you push updated artifacthub-pkg.yml files to your default branch.

Checksum example:

sha256sum my-headlamp-plugin-0.1.0.tar.gz

CI/CD

CI (ci.yaml)

Runs on every push to main and every pull request. Delegates to the shared plugin-ci.yaml workflow which runs:

• TypeScript typecheck (tsc --noEmit)
• ESLint
• Prettier format check
• Vitest test suite
• Production build

Release (release.yaml)

Triggered manually from the GitHub Actions UI with a version input (e.g. 1.0.0). Delegates to the shared plugin-release.yaml workflow which:

• Bumps the version in package.json
• Runs headlamp-plugin package to produce a .tar.gz artifact
• Creates a GitHub release with the artifact attached
• Updates artifacthub-pkg.yml with the new version and archive URL

Resources

• Headlamp documentation
• Headlamp plugin development guide
• Headlamp SDK API reference
• ArtifactHub Headlamp plugins
• Headlamp GitHub