@kinvolk/headlamp-plugin 0.15.0-alpha.0 is a prerelease of the next minor SDK/toolkit version, following stable 0.14.0. It brings newer plugin APIs, Storybook 10 and Vitest 5 tooling, and packaging fixes for plugin authors.
headlamp-plugin is used by Headlamp plugins, and is used by Headlamp plugin authors.
New and expanded plugin APIs
| API | What plugins can do | Change / credit |
|---|---|---|
New exports: ResourceMap.GraphView, ResourceMap.KubeIcon
| Embed the resource-map renderer and Kubernetes icons in plugin pages. | #6992, thanks @rootp1 |
New: registerResourceRelationProvider
| Add custom resource-map relationships, such as implicit dependencies not represented by owner references. | #5453, thanks @Joshna907 |
New: registerProjectApiResource
| Include additional namespaced API resources, including CRDs, in Project resource fetching, counts, and health. | #5571, thanks @NAME-ASHWANIYADAV |
New: registerProjectGrouping
| Control how labelled namespaces are grouped into Projects, including grouping across clusters. | #6905, thanks @illume |
Expanded: registerCustomCreateProject with new DefaultCreateProject.NEW_PROJECT / FROM_YAML IDs
| Replace either built-in project creation choice, rather than only adding another choice. | #7280, thanks @illume |
Expanded: registerAppTheme(theme, { default: true })
| Select a first-use default theme while preserving user preferences and administrator-forced themes. | #7613, thanks @illume |
New: registerHomeSidebarEntryFilter
| Filter or modify Home navigation entries independently of the in-cluster sidebar. | #6111, thanks @Suyog241005 |
New: registerClusterEmptyState and ClusterEmptyStateProps
| Replace or wrap no-clusters onboarding, optionally retaining Headlamp's standard fallback content. | #7075, thanks @illume |
These APIs are exported from @kinvolk/headlamp-plugin/lib; the map components are also available through @kinvolk/headlamp-plugin/lib/ResourceMap. New SDK declarations do not add APIs to older Headlamp hosts. Test these integrations against a host that implements the corresponding APIs.
Tooling and fixes
- Storybook 10.6.3 and Vitest 5.0.4. Updated the shared Storybook configuration to ESM, aligned coverage tooling and jest-dom matcher types, and updated the generated plugin template. See migration notes below before upgrading existing plugins. (#8161, #8028, thanks @skoeva)
- Windows Storybook startup. Use the CLI's cross-platform launcher instead of the Unix-style command that failed in native Windows shells. (#6995, thanks @KariraLakshya)
- Complete i18n packaging. Include
i18nextSharedConfig.mjsand its declaration file so plugin tests importing i18n do not fail with a missing-module error. (#8040, thanks @skoeva) - Updated TypeScript configuration. Use bundler module resolution and remove the deprecated
baseUrlconfiguration from the shared plugin config. (#6439, #6515, thanks @Athang69) - Smaller network transfers. Plugin builds generate Brotli
.brsidecars alongside assets; compatible Headlamp servers can serve them with fallback to the original files. (#6004, thanks @illume) - More useful isolated stories. Expanded Pod, CRD, Deployment, StatefulSet, DaemonSet, ReplicaSet, Job, and CronJob Storybook mocks to avoid unintended API requests. (#6832, #7297, #7438, #7473, thanks @illume)
- Dependency maintenance. Updated toolkit dependencies and removed unused
humanize-durationand its types. (#6679, #7787, #7870, #7881, #8028, #8126, #8161, #8167, thanks @illume, @dependabot[bot], and @skoeva; #8056, thanks @rahullli)
Upgrade and migration notes
Use the existing headlamp-plugin upgrade command, rather than only installing a new package. After publication, explicitly select this prerelease for both the command and its upgrade target:
npx @kinvolk/headlamp-plugin@0.15.0-alpha.0 upgrade --headlamp-plugin-version=0.15.0-alpha.0 your-plugin-folderOr follow the published alpha dist-tag:
npx @kinvolk/headlamp-plugin@alpha upgrade --headlamp-plugin-version=alpha your-plugin-folderCommit or back up your plugin first. The command refreshes template-managed scripts, TypeScript files, lint configuration, and overrides; rebuilds the lockfile and installed dependencies; runs npm audit fix; and formats, lints, and type-checks the plugin. In this release, the template includes the Vitest 5 / Istanbul coverage overrides and patched middleware override. Review the resulting diff: template-managed settings are replaced, not merged, and the audit step can update other dependencies.
- Node: plugin development requires Node 22.12 or newer supported by Vitest 5. Istanbul coverage's Babel dependencies require Node 22.18+ on the Node 22 line, or Node 24.11+ on the Node 24 line.
- Storybook: the shared configuration is now
config/.storybook/main.mjs. The upgrader does not convert custom CommonJS configuration; migrate it to ESM and review any custom scripts after the template scripts are refreshed. - Separately declared tooling: review direct Vitest, coverage, or Storybook dependencies for compatibility. The upgrader updates template overrides; it does not migrate every custom dependency declaration.
- Existing plugin overrides: the upgrader copies the template's
webpack-dev-middlewareoverride (^7.4.6) into the plugin project. npm does not inherit dependency-package overrides. - Validation: the command does not run your plugin build, test suite, or Storybook build; run those after upgrading.
- Desktop development: packaged Headlamp apps require Plugin Development Mode and a native trust confirmation to load development-inventory plugins. Electron development builds retain automatic loading. This is host behavior, not something installing the SDK enables. (#7628, thanks @illume)
- Desktop commands: command authorization is defined by the host product's manifest and verified plugin identity. Installing this SDK or granting user consent does not itself authorize a command. (#7570, thanks @illume)
Example: replace built-in project creation choices
Existing screenshot from merged #7280, using the SDK extension points in a compatible Headlamp host. This is not new validation of the release-preparation PR.
| Default choices | Plugin replacements |
|---|---|
| 
|