Skip to main content

Manifest and Property Inspectors

The manifest is the contract

The manifest tells Stream Deck what your plugin is, how to run it, what actions it exposes, which devices and OS versions it supports, and where the configuration UI lives.

1. Manifest responsibilities​

manifest.json defines:

  • plugin name, author, version, description, icon, and UUID,
  • the entry point through CodePath,
  • supported operating systems,
  • minimum Stream Deck software version,
  • Node.js runtime configuration,
  • actions and their metadata,
  • key and dial controller support,
  • action states and images,
  • property inspector paths,
  • predefined profiles,
  • optional app monitoring metadata.

Use the schema URL for validation:

{
  "$schema": "https://schemas.elgato.com/streamdeck/plugins/manifest.json"
}

2. Minimal manifest shape​

{
  "$schema": "https://schemas.elgato.com/streamdeck/plugins/manifest.json",
  "Author": "Example",
  "Name": "Deploy Tools",
  "Description": "Deployment shortcuts for Stream Deck.",
  "Icon": "imgs/plugin-icon",
  "Version": "1.0.0.0",
  "UUID": "com.example.deploy-tools",
  "CodePath": "bin/plugin.js",
  "SDKVersion": 2,
  "Software": {
    "MinimumVersion": "7.1"
  },
  "Nodejs": {
    "Version": "24"
  },
  "OS": [
    { "Platform": "mac", "MinimumVersion": "13" },
    { "Platform": "windows", "MinimumVersion": "10" }
  ],
  "Actions": [
    {
      "UUID": "com.example.deploy-tools.deploy",
      "Name": "Deploy",
      "Icon": "imgs/deploy-icon",
      "PropertyInspectorPath": "ui/deploy.html",
      "States": [
        {
          "Image": "imgs/deploy"
        }
      ]
    }
  ]
}

3. Action metadata​

Each action needs:

  • a stable action UUID prefixed by the plugin UUID,
  • a readable action name,
  • an icon,
  • states and images where appropriate,
  • optional controller support for keys and dials,
  • optional property inspector path.

Use one action for one user-facing behavior. Do not hide many unrelated behaviors behind one action unless the property inspector makes the mode obvious.

4. Keys, dials, and controllers​

Key actions target keypad-style controls. Dial actions target Stream Deck + encoders and their touchscreen area.

If an action supports both, declare it explicitly:

{
  "UUID": "com.example.audio.volume",
  "Name": "Volume",
  "Controllers": ["Keypad", "Encoder"],
  "Icon": "imgs/volume",
  "States": [
    {
      "Image": "imgs/volume"
    }
  ],
  "Encoder": {
    "layout": "$B1",
    "TriggerDescription": {
      "Rotate": "Adjust volume",
      "Push": "Mute"
    }
  }
}

Do not add dial support just because it is available. Add it when rotation or the touch strip makes the action better.

5. Property inspectors​

Property inspectors are HTML web views used to configure actions. Put them under *.sdPlugin/ui/ and reference them from manifest.json.

{
  "Actions": [
    {
      "UUID": "com.example.deploy-tools.deploy",
      "Name": "Deploy",
      "PropertyInspectorPath": "ui/deploy.html"
    }
  ]
}

Use a property inspector for:

  • target selection,
  • mode selection,
  • labels,
  • display preferences,
  • per-action IDs,
  • non-secret configuration.

Avoid property inspectors for:

  • secrets,
  • large tables,
  • account onboarding flows,
  • workflows that need a full browser window.

6. Basic property inspector​

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Deploy Settings</title>
    <script src="sdpi-components.js"></script>
  </head>
  <body>
    <sdpi-item label="Environment">
      <sdpi-select setting="environment">
        <option value="staging">Staging</option>
        <option value="production">Production</option>
      </sdpi-select>
    </sdpi-item>

    <sdpi-item label="Service">
      <sdpi-textfield setting="serviceName" placeholder="api"></sdpi-textfield>
    </sdpi-item>
  </body>
</html>

Elgato's property inspector docs recommend using the UI component library locally for predictable offline behavior.

7. Settings design​

Use one settings type per action:

type DeploySettings = {
  environment?: 'staging' | 'production';
  serviceName?: string;
};

Set defaults in action code, not only in the UI:

const environment = ev.payload.settings.environment ?? 'staging';
const serviceName = ev.payload.settings.serviceName ?? 'api';

That keeps the action resilient when:

  • users add the action before opening the inspector,
  • settings are from an older plugin version,
  • inspector fields were removed or renamed,
  • profiles were imported from another machine.

8. Versioning settings​

When settings evolve, use tolerant reads:

type SettingsV1 = {
  target?: string;
};

type SettingsV2 = {
  target?: string;
  displayMode?: 'status' | 'compact';
};

function normalizeSettings(settings: SettingsV1 | SettingsV2): Required<SettingsV2> {
  return {
    target: settings.target ?? 'default',
    displayMode: 'displayMode' in settings ? settings.displayMode ?? 'status' : 'status',
  };
}

Avoid forced migrations unless you really need them. Most Stream Deck settings can be normalized at read time.

9. Manifest quality checklist​

  • Plugin UUID is stable and reverse-DNS formatted.
  • Action UUIDs are prefixed with the plugin UUID.
  • CodePath points to the built entry file.
  • Nodejs.Version matches the current SDK requirement.
  • Icons and state images exist in the packaged directory.
  • Property inspector paths are relative to the plugin directory.
  • Minimum OS and Stream Deck versions match the features you use.
  • Schema validation passes.