plugins: Add concept of "shipped", "user-installed", and "dev" plugin types #4095

joaquimrocha · 2025-10-28T12:12:18Z

Summary

Define plugins as being of different types (shipped/user-installed/dev) and load them according to the description set in #3628 .

Related Issue

Fixes #3628 .

Steps to Test

(use the app)

Run the development version of a plugin that's shipped (like the Prometheus one) and verify that it takes precedence over the shipped one: make sure you change something in the plugin and see it showing in the UI
Do the same for a plugin you have also installed with the catalog.
Play with the plugin settings to see if it's reflecting reality and desire

tested on windows cmd
tested on windows WSL
tested on linux bash
tested on macOS zsh
does npm start run inside a plugin print the correct folder where the plugin is copied to?
compiled app loads plugins as expected
development mode loads plugins as expected
plugins load in-cluster as expected
test with an existing plugin installed, does that still get loaded?

Screenshots (if applicable)

Copilot

Pull Request Overview

This PR implements a plugin loading system that differentiates plugins by type (shipped/user-installed/development) and loads them according to a priority-based system. Development plugins have the highest priority, followed by user-installed, then shipped plugins. When multiple versions of the same plugin exist, only the highest priority enabled version is loaded.

Key Changes:

Backend now returns plugin metadata including type (development/user/shipped) alongside path
Frontend applies priority-based loading logic, marking which plugin versions are loaded vs overridden
New user-plugins directory introduced to separate user-installed plugins from development plugins
UI updated to display plugin type, status (Loaded/Not Loaded/Disabled), and override information

Reviewed Changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`plugins/pluginctl/src/plugin-management.js`	Updated default plugins directory from 'plugins' to 'user-plugins'
`frontend/src/plugin/pluginsSlice.ts`	Added type, isLoaded, and overriddenBy fields to PluginInfo type
`frontend/src/plugin/index.ts`	Implemented applyPluginPriority function and updated plugin loading logic
`frontend/src/components/App/PluginSettings/PluginSettings.tsx`	Added Type column and updated Status column to show override information
`frontend/src/components/App/PluginSettings/PluginSettingsDetails.tsx`	Added type chip display to plugin details header
`backend/pkg/plugins/plugins.go`	Implemented PluginMetadata struct and updated functions to handle three plugin directories
`backend/pkg/config/config.go`	Added UserPluginsDir configuration and defaultUserPluginDir function
`backend/cmd/server.go`	Updated to pass UserPluginDir to configuration
`app/electron/plugin-management.ts`	Added defaultUserPluginsDir function and updated install/update methods
Multiple snapshot files	Updated test snapshots to reflect new Type column and Status display changes

Comments suppressed due to low confidence (1)

frontend/src/plugin/index.ts:1

The comment on line 286 states plugins with the same name are treated as separate entries, but the actual implementation in applyPluginPriority groups them by name and applies priority logic. This comment is misleading about the actual behavior.

/*

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

backend/cmd/headlamp.go

frontend/src/plugin/index.ts

frontend/src/components/App/PluginSettings/PluginSettings.tsx

app/electron/main.ts

frontend/src/plugin/index.ts

illume

@joaquimrocha seems there's some issues with CI checks?

Can you please add some tests for some of the changes?

What happens to plugins people already have installed in the old plugins directory? Will plugins installed to the old folder be ignored by this new code?

joaquimrocha · 2025-10-28T12:39:42Z

What happens to plugins people already have installed in the old plugins directory?

I guess they will still be interpreted as dev plugins. Hmm, this actually can be a problem if we installed the plugins in the old fashion into plugins/ and now they are assumed to be dev plugins which will take over priority over any updates. Let me quickly see if I can have a migration path.

joaquimrocha · 2025-10-28T12:41:08Z

@joaquimrocha seems there's some issues with CI checks?

Can you please add some tests for some of the changes?

I have new stories in the last commit.

illume · 2025-10-29T11:34:30Z

One of the checks is failing.

Some of the commit subject lines need the context part added.
For backend changes we are more strict about requiring tests now.

backend/pkg/config/config.go

skoeva · 2025-11-05T17:00:16Z

updated the failing snapshots and rebased against main again

illume · 2025-11-05T17:28:24Z

Maybe not for this PR, but this issue would be a good improvement:

I think we should have the plugin path listed for each plugin. A couple of us got confused where plugins were.
It was not clear to a couple of us that the user-plugins folder was where Plugin Catalog installed plugins were installed. Shall we show the user after installing a plugin where the plugin was installed to?

joaquimrocha · 2025-11-05T20:25:28Z

Maybe not for this PR, but this issue would be a good improvement:

I think we should have the plugin path listed for each plugin. A couple of us got confused where plugins were.

It was not clear to a couple of us that the user-plugins folder was where Plugin Catalog installed plugins were installed. Shall we show the user after installing a plugin where the plugin was installed to?

I can add an "open folder" button to each plugin but in its details view. WDYT?

vyncent-t · 2025-11-05T21:20:29Z

Tried the latest changes on my end, for me the app-catalog does not have the disabled button for the non priority one, the multiple versions flag works though.

Steps

Install a plugin from the plugins repo that we currently ship, prometheus etc (ensure it is in the .config/Headlamp/plugins )

Run the linux built app

Nav to the settings page then plugins tab

Note that the flag for multiple versions works but the toggles are both still on

Seen w/ @illume @skoeva

Tried installing dev plugins using app-catalog 0.7.0 and an older dev app-catalog 0.6.3, both are still shown as enabled toggles like in this image.

Used:
Shipped app-catalog 0.7.0 + Dev app-catalog 0.7.0
Shipped app-catalog 0.7.0 + Dev app-catalog 0.6.3

vyncent-t · 2025-11-05T23:16:44Z

Tried the latest changes on my end, for me the app-catalog does not have the disabled button for the non priority one, the multiple versions flag works though.

Steps

Install a plugin from the plugins repo that we currently ship, prometheus etc (ensure it is in the .config/Headlamp/plugins )

Run the linux built app

Nav to the settings page then plugins tab

Note that the flag for multiple versions works but the toggles are both still on

Seen w/ @illume @skoeva

Tried installing dev plugins using app-catalog 0.7.0 and an older dev app-catalog 0.6.3, both are still shown as enabled toggles like in this image.

Used: Shipped app-catalog 0.7.0 + Dev app-catalog 0.7.0 Shipped app-catalog 0.7.0 + Dev app-catalog 0.6.3

Also noticed that "Reload" button not working here may be due to the use of the .config/Headlamp/user-plugins, maybe we can have the changes made in that dir kick off a reload the same way .config/Headlamp/plugins does. WDYT? @joaquimrocha

vyncent-t · 2025-11-06T22:34:12Z

@joaquimrocha
Just tried the changes and everything looks good 👍 great stuff

Can use reload button after installing plugin, plugin now renders in list
Can use manual app refresh after installing plugin, plugin now renders in list
Can manually remove plugins from .config/Headlamp/user-plugins and refresh app (ghost plugins gone)
Disabled plugins that are not loaded now also working

illume

Looking good.

Some issues in CI though...

rebase to fix this conflict in app/electron/preload.ts
make backend-lint
make frontend-test
- snapshots need an update
- src/components/App/PluginSettings/PluginSettingsDetails.tsx:17:10 - error TS2300: Duplicate identifier 'Typography'.

Copilot

Pull Request Overview

Copilot reviewed 38 out of 38 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-07T10:22:54Z

frontend/src/components/App/PluginSettings/PluginSettingsDetails.tsx

+import { Typography } from '@mui/material';
 import Box, { BoxProps } from '@mui/material/Box';
 import Button from '@mui/material/Button';
+import Chip from '@mui/material/Chip';
 import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';


Typography is imported twice - once from '@mui/material' on line 17 and again on line 22. Remove the duplicate import on line 17.

frontend/src/plugin/index.ts

Copilot · 2025-11-07T10:22:55Z

backend/pkg/plugins/plugins.go

+			if !os.IsNotExist(err) {
+				logger.Log(logger.LevelInfo, map[string]string{"pluginPath": pluginPath},
+					err, "Not including plugin path, error checking main.js")
+			}


The comment says 'Only log if it's not a "does not exist" error (which is expected during deletion)' but this logging is at LevelInfo. During deletion, there may be race conditions where the directory is being removed. Consider using a more specific log level or adding context about whether this is during a deletion operation.

nit, This would be nice to have, but we can skip it for now.

Copilot · 2025-11-07T10:22:55Z

frontend/src/components/App/PluginSettings/PluginSettings.tsx

+        if (newEnabledState && p.name === plugName && p.type !== plugType) {
+          return { ...p, isEnabled: false };
        }


When enabling one version of a plugin, this automatically disables all other versions with the same name. This behavior should be documented in the function's JSDoc comment as it's a significant side effect that affects user data.

nit, This would be nice to have, but we can skip it for now.

Copilot · 2025-11-07T10:22:55Z

backend/pkg/plugins/plugins.go

+func Delete(userPluginDir, pluginDir, filename, pluginType string) error {
+	// Validate plugin type if provided
+	if pluginType != "" && pluginType != "user" && pluginType != "development" {
+		return fmt.Errorf("invalid plugin type '%s': must be 'user' or 'development'", pluginType)


The 'shipped' plugin type exists in the system but is not allowed for deletion. The error message should clarify that shipped plugins cannot be deleted, rather than implying 'shipped' is invalid. Consider: "invalid plugin type '%s': must be 'user' or 'development' (shipped plugins cannot be deleted)"

Suggested change

return fmt.Errorf("invalid plugin type '%s': must be 'user' or 'development'", pluginType)

return fmt.Errorf("invalid plugin type '%s': must be 'user' or 'development' (shipped plugins cannot be deleted)", pluginType)

nit, This message improvement would be nice-to-have, we could skip it for now.

frontend/src/components/App/PluginSettings/PluginSettings.tsx

This will be used for the catalog-installed plugins, so we end up with static, user, and dev plugins. Static are plugins shipped in Headlamp. User are plugins installed by the user (via the catalog). Dev are plugins used during development, like when we are adding a new feature to a plugin.

Type being shipped/user/dev.

Allow specifying plugin type ('user' or 'development') when deleting plugins. This prevents accidentally deleting the wrong plugin when plugins with the same name exist in both directories. When type is specified, only that directory is checked. When omitted, maintains backward compatibility by checking both directories in priority order (user-plugins first, then development).

Now that we have introduced user-installed plugins as a different location.

Otherwise, when there are many plugins in the page, the button is pushed down and can appear as if there is no Save button.

To be consistent with other designs we have.

From the PluginSettingsDetails.

k8s-ci-robot requested review from sniok and vyncent-t October 28, 2025 12:12

k8s-ci-robot added approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Oct 28, 2025

joaquimrocha requested review from illume and skoeva and removed request for sniok and vyncent-t October 28, 2025 12:12

k8s-ci-robot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Oct 28, 2025

illume added this to the v0.37.0 milestone Oct 28, 2025

illume added backend Issues related to the backend frontend Issues related to the frontend plugins labels Oct 28, 2025

illume requested a review from Copilot October 28, 2025 12:23

Copilot AI reviewed Oct 28, 2025

View reviewed changes

illume requested changes Oct 28, 2025

View reviewed changes

joaquimrocha force-pushed the plugin-loading-changes branch 6 times, most recently from 3336ce8 to f10ee45 Compare October 29, 2025 09:51

joaquimrocha force-pushed the plugin-loading-changes branch from a8ec734 to 7fad445 Compare October 29, 2025 13:08

illume reviewed Oct 29, 2025

View reviewed changes

backend/pkg/config/config.go Show resolved Hide resolved

illume changed the title ~~Plugin loading changes~~ plugins: Add "user" plugins, plugin settings UI updates, and change loading priority Oct 29, 2025

skoeva force-pushed the plugin-loading-changes branch from 7fad445 to 87803ab Compare October 29, 2025 13:44

illume changed the title ~~plugins: Add "user" plugins, plugin settings UI updates, and change loading priority~~ plugins: Add concepts of (shipped/user-installed/dev) types of plugins with settings UI updates, and loading priorities for different plugin types Oct 29, 2025

skoeva force-pushed the plugin-loading-changes branch from f4628a9 to e9bf6ad Compare November 5, 2025 16:59

joaquimrocha force-pushed the plugin-loading-changes branch from e9bf6ad to b18d540 Compare November 5, 2025 20:33

skoeva force-pushed the plugin-loading-changes branch from b18d540 to b750fb1 Compare November 6, 2025 14:53

joaquimrocha force-pushed the plugin-loading-changes branch from b750fb1 to 2b0c30b Compare November 6, 2025 15:00

skoeva force-pushed the plugin-loading-changes branch from 2b0c30b to 42c3ba6 Compare November 6, 2025 17:52

joaquimrocha force-pushed the plugin-loading-changes branch from 42c3ba6 to f52c88f Compare November 6, 2025 22:17

illume requested changes Nov 7, 2025

View reviewed changes

illume requested a review from Copilot November 7, 2025 10:15

Copilot AI reviewed Nov 7, 2025

View reviewed changes

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 7, 2025

skoeva force-pushed the plugin-loading-changes branch from f52c88f to 2eff944 Compare November 7, 2025 14:48

joaquimrocha added 11 commits November 7, 2025 09:50

backend,frontend: Add info about plugins' type when handling them

58b8cdd

Type being shipped/user/dev.

backend,frontend: Load plugins according in a priority to their type

e5f8a7d

app: Account for plugins coming from different locations

4b9201e

Now that we have introduced user-installed plugins as a different location.

frontend/PluginSettings: Show plugins according to their type

5b2795e

frontend/PluginSettingsDetails: Add the type of plugin to the header

f71858c

frontend/PluginSettings: Make the Save button always visible in the page

edb20ed

Otherwise, when there are many plugins in the page, the button is pushed down and can appear as if there is no Save button.

frontend: Properly delete plugins according to their type

ed32403

frontend/PluginSettingsDetails: Move the plugin button to the top right

fd7c573

To be consistent with other designs we have.

app,frontend: Allow to open the plugin folder

2e5b032

From the PluginSettingsDetails.

skoeva force-pushed the plugin-loading-changes branch from 2eff944 to 2e5b032 Compare November 7, 2025 14:51

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 7, 2025

	return fmt.Errorf("invalid plugin type '%s': must be 'user' or 'development'", pluginType)
	return fmt.Errorf("invalid plugin type '%s': must be 'user' or 'development' (shipped plugins cannot be deleted)", pluginType)

plugins: Add concept of "shipped", "user-installed", and "dev" plugin types #4095

Are you sure you want to change the base?

plugins: Add concept of "shipped", "user-installed", and "dev" plugin types #4095

Conversation

joaquimrocha commented Oct 28, 2025 • edited by illume Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Steps to Test

Screenshots (if applicable)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

illume left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joaquimrocha commented Oct 28, 2025

Uh oh!

joaquimrocha commented Oct 28, 2025

Uh oh!

illume commented Oct 29, 2025

Uh oh!

Uh oh!

skoeva commented Nov 5, 2025

Uh oh!

illume commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joaquimrocha commented Nov 5, 2025

Uh oh!

vyncent-t commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vyncent-t commented Nov 5, 2025

Uh oh!

vyncent-t commented Nov 6, 2025

Uh oh!

illume left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

illume Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

illume Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

illume Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

joaquimrocha commented Oct 28, 2025 •

edited by illume

Loading

illume left a comment •

edited

Loading

illume commented Nov 5, 2025 •

edited

Loading

vyncent-t commented Nov 5, 2025 •

edited

Loading

illume left a comment •

edited

Loading

illume Nov 7, 2025 •

edited

Loading