privilegedescalation/headlamp-plugin-template

Files

T

Gandalf the Greybeard 9da27f4186 feat: scaffold starter template with TypeScript, CRD list view, CI, ArtifactHub

Adds full plugin starter template including:
- package.json with @kinvolk/headlamp-plugin devDependency and standard scripts
- tsconfig.json extending headlamp plugin config
- vitest.config.mts + vitest.setup.ts (jsdom, NODE_ENV=test, localStorage shim)
- src/index.tsx: registers sidebar entry and route for ResourceListPage
- src/components/ResourceListPage.tsx: placeholder CRD list view with TODO guide
- src/components/ResourceListPage.test.tsx: example tests using vi.mock pattern
- .github/workflows/ci.yaml: delegates to shared plugin-ci.yaml
- .github/workflows/release.yaml: delegates to shared plugin-release.yaml
- artifacthub-pkg.yml + artifacthub-repo.yml: ArtifactHub metadata with TODO markers
- renovate.json: Mend Renovate config for weekly dependency updates
- README.md: complete getting-started guide
- CONTRIBUTING.md: local dev, code style, testing, PR process
- LICENSE: Apache-2.0

Co-Authored-By: Paperclip <noreply@paperclip.ing>

2026-03-21 03:45:12 +00:00

2.6 KiB

Raw Permalink Blame History

Contributing

Thank you for your interest in contributing. This guide covers how to work on this plugin locally and what to expect from the review process.

Running the plugin locally

Prerequisites

Node.js 18 or later
A running Headlamp instance (desktop app or headlamp-server)

Setup

npm install
npm start

npm start runs headlamp-plugin start, which starts a dev server at http://localhost:4466. Headlamp will hot-reload the plugin as you save files.

To connect Headlamp to your local dev server, use the in-app plugin manager or set the plugin source URL to http://localhost:4466.

Build

npm run build

Produces a production bundle in dist/. Copy the dist/ folder to your Headlamp plugins directory:

Linux: ~/.config/Headlamp/plugins/<plugin-name>/
macOS: ~/Library/Application Support/Headlamp/plugins/<plugin-name>/
Windows: %APPDATA%\Headlamp\plugins\<plugin-name>\

Code style

This project uses TypeScript, ESLint, and Prettier. All configuration is provided by @kinvolk/headlamp-plugin.

Check types:

npm run tsc

Lint:

npm run lint
npm run lint:fix   # auto-fix where possible

Format:

npm run format          # write changes
npm run format:check    # check only (used in CI)

CI will fail if any of these checks fail. Run them locally before opening a PR.

Testing

All new code must have tests. Run the suite with:

npm test

Watch mode during development:

npm run test:watch

Tests use Vitest with React Testing Library and the jsdom environment. Key conventions:

Place test files alongside the component they test, named ComponentName.test.tsx.
Mock @kinvolk/headlamp-plugin/lib/CommonComponents using vi.mock — see src/components/ResourceListPage.test.tsx for the established pattern.
Avoid testing implementation details; prefer assertions against rendered output.

Pull request process

Fork the repository and create a branch from main.
Make your changes with tests.
Ensure npm run tsc, npm run lint, npm run format:check, and npm test all pass.
Open a pull request against main with a clear description of what changed and why.
The CI workflow will run automatically. Address any failures before requesting review.
A maintainer will review and merge the PR.

Releasing

Releases are triggered manually via the Release GitHub Actions workflow. Maintainers run this workflow with the target version number; it packages the plugin, creates a GitHub release, and updates the ArtifactHub metadata.

2.6 KiB Raw Permalink Blame History