OpenParable
Skip to content
← Back to skills

Extension Features

Development
extension-features

Extension Features is an Agent Skill for development published in the podman-desktop/podman-desktop repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guide for working with the Podman Desktop extension feature mechanism: declaring features in an extension manifest, how the registry propagates them to the renderer, and how Svelte components detect active features. Use when adding a new feature declaration to an extension, writing renderer code that reacts to an extension being active/inactive, or debugging why a feature flag is not being picked up.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/podman-desktop/podman-desktop/blob/HEAD/.agents/skills/extension-features/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/extension-features, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Extension Features in Podman Desktop

Extensions can advertise named capabilities ("features") that the renderer watches. Any Svelte component can reactively detect whether a feature is currently active without knowing which extension registered it.

Key files

FileRole
packages/main/src/plugin/feature-registry.tsFeatureRegistry — stores features, fires IPC on changes
packages/main/src/plugin/extension/extension-loader.tsReads contributes.features from the manifest and calls registerFeatures() on activation
packages/main/src/plugin/extension/extension-manifest-schema.tsZod schema — features is z.array(z.string()).optional()
packages/renderer/src/stores/registered-features.tsSvelte store + event target for the renderer
packages/renderer/src/PreferencesNavigation.svelteReal-world usage example

1 — Declaring a feature in an extension

Add a features array under contributes in the extension's package.json:

{
  "contributes": {
    "features": ["my-feature-name"]
  }
}

The extension loader reads this at activation time and calls featureRegistry.registerFeatures(extensionId, features[]) automatically. The returned Disposable is added to the extension's subscriptions, so the feature is unregistered when the extension is deactivated — no manual cleanup needed.


2 — How the registry works (main process)

FeatureRegistry (packages/main/src/plugin/feature-registry.ts):

  • Stores a Map<extensionId, string[]>.
  • registerFeatures(extensionId, features) — sets the entry and fires onFeaturesUpdated.
  • unregisterFeatures(extensionId) — removes the entry and fires onFeaturesUpdated.
  • On every onFeaturesUpdated, sends feature-registry:features-updated (with the flat list of all current features) to the renderer via apiSender.
  • Handles the IPC call feature-registry:getRegisteredFeatures so the renderer can fetch the current list on startup.

3 — Renderer store (registered-features.ts)

import { registeredFeatures, onDidChangeRegisteredFeatures } from '/@/stores/registered-features';

registeredFeatures

A Writable<string[]> Svelte store. Updated by EventStore whenever feature-registry:features-updated fires or on system-ready.

onDidChangeRegisteredFeatures

An EventTarget that dispatches a CustomEvent<boolean> per feature name:

  • detail === true → feature was just added
  • detail === false → feature was just removed

4 — Detecting a feature in a Svelte component

Pattern A — reactive store (simplest, covers initial state)

<script lang="ts">
  import { registeredFeatures } from '/@/stores/registered-features';

  // Reactive: true whenever the feature is in the current list
  let featureActive = $derived($registeredFeatures.includes('my-feature-name'));
</script>

{#if featureActive}
  <!-- feature-specific UI -->
{/if}

Pattern B — store subscription + event listener (for side effects)

Use this when detecting a feature should trigger imperative logic (e.g. toggling visibility of a nav item), following the pattern in PreferencesNavigation.svelte:

<script lang="ts">
  import { onMount } from 'svelte';
  import { onDidChangeRegisteredFeatures, registeredFeatures } from '/@/stores/registered-features';

  const FEATURE = 'my-feature-name';

  let featureActive = $state(false);

  function applyFeatureState(enabled: boolean): void {
    featureActive = enabled;
    // ... other imperative updates
  }

  const featureListener = (event: Event): void => {
    applyFeatureState((event as CustomEvent<boolean>).detail);
  };

  onMount(() => {
    // 1. Listen for future changes
    onDidChangeRegisteredFeatures.addEventListener(FEATURE, featureListener);

    // 2. Sync with current state (handles features already active at mount time)
    const unsub = registeredFeatures.subscribe(features => {
      applyFeatureState(features.includes(FEATURE));
    });

    return (): void => {
      onDidChangeRegisteredFeatures.removeEventListener(FEATURE, featureListener);
      unsub();
    };
  });
</script>

Why both? The event listener catches changes that happen after mount. The store subscription catches the state that was already true at mount. Using only the event listener misses features that were registered before the component mounted.


5 — Existing feature names

Feature stringRegistered byEffect in renderer
kubernetes-contexts-managerkube-context extensionHides the built-in Kubernetes section in Preferences navigation

6 — End-to-end flow summary

extension package.json
  └─ contributes.features: ["my-feature"]
        │
        ▼  (extension activates)
extension-loader.ts
  └─ featureRegistry.registerFeatures(extensionId, ["my-feature"])
        │
        ▼
FeatureRegistry
  ├─ stores in Map
  └─ fires onFeaturesUpdated → apiSender.send("feature-registry:features-updated", [...])
        │
        ▼  (IPC to renderer)
registered-features.ts (EventStore)
  ├─ updates registeredFeatures store
  └─ dispatches CustomEvent on onDidChangeRegisteredFeatures
        │
        ▼
Svelte component
  └─ reacts via $derived / subscribe / addEventListener