JavaScript- und TypeScript-Plugins

Standardweg

Für ein einfaches, schnelles, installierbares Stream Deck Plugin nutze das offizielle Elgato SDK mit TypeScript.

1. Voraussetzungen

Die aktuelle Doku zum Elgato SDK 2.0.0 listet:

• Node.js 24 oder neuer.
• Stream Deck App 7.1 oder neuer.
• Stream Deck Hardware oder Stream Deck Mobile für grundlegende Tests.
• Die Stream Deck CLI von npm.
• Einen Texteditor mit TypeScript-Unterstützung.

Installiere die CLI:

npm install -g @elgato/cli@latest
streamdeck -v

Die CLI hat außerdem den Kurz-Alias sd.

2. Ein Plugin erstellen

streamdeck create

Verwende eine Reverse-DNS-UUID:

com.yourcompany.timer
com.yourcompany.deployment-panel
de.example.obs-tools

Halte UUIDs klein geschrieben und stabil. Sobald Nutzende Actions in ihren Profilen haben, brechen das Ändern von Plugin- oder Action-UUIDs diese Zuordnungen.

3. Struktur des generierten Projekts

.
├── com.example.timer.sdPlugin/
│   ├── bin/
│   ├── imgs/
│   ├── logs/
│   ├── ui/
│   └── manifest.json
├── src/
│   ├── actions/
│   └── plugin.ts
├── package.json
├── rollup.config.mjs
└── tsconfig.json

Die wichtige Aufteilung:

• src/ enthält den Quellcode.
• *.sdPlugin/ ist das kompilierte Plugin-Verzeichnis, das Stream Deck lädt.
• manifest.json beschreibt Plugin-Metadaten, Actions, Icons, unterstützte OS-Versionen, Node-Einstellungen und UI-Pfade.
• ui/ enthält Property-Inspector-HTML.
• imgs/ enthält Plugin-/Action-Grafiken.
• logs/ wird vom SDK-Logger verwendet.

4. Entwicklungsschleife

npm run watch

Das im Scaffold enthaltene Watch-Skript baut das Plugin und startet es in Stream Deck neu, wenn sich Quell- oder Manifest-Dateien ändern.

Manuelle Schleife:

npm run build
streamdeck restart com.example.timer

Nützliche CLI-Befehle:

streamdeck link path/to/com.example.timer.sdPlugin
streamdeck list
streamdeck restart com.example.timer
streamdeck stop com.example.timer
streamdeck validate path/to/com.example.timer.sdPlugin
streamdeck pack path/to/com.example.timer.sdPlugin

5. Minimale Action

import { action, KeyDownEvent, SingletonAction, WillAppearEvent } from '@elgato/streamdeck';

type CounterSettings = {
  count?: number;
};

@action({ UUID: 'com.example.timer.counter' })
export class CounterAction extends SingletonAction<CounterSettings> {
  override async onWillAppear(ev: WillAppearEvent<CounterSettings>): Promise<void> {
    await ev.action.setTitle(`${ev.payload.settings.count ?? 0}`);
  }

  override async onKeyDown(ev: KeyDownEvent<CounterSettings>): Promise<void> {
    const count = (ev.payload.settings.count ?? 0) + 1;

    await ev.action.setSettings({ count });
    await ev.action.setTitle(`${count}`);
  }
}

Dieses Muster reicht für viele einfache Plugins:

1. Lies die Einstellungen aus dem Event-Payload.
2. Führe eine kurze Aktion aus.
3. Persistiere geänderte Einstellungen.
4. Aktualisiere den visuellen Zustand.

6. Die Action registrieren

Die Action braucht sowohl Implementierung als auch Manifest-Metadaten.

{
  "$schema": "https://schemas.elgato.com/streamdeck/plugins/manifest.json",
  "Author": "Example",
  "Name": "Timer Tools",
  "Description": "Small Stream Deck timer utilities.",
  "Version": "1.0.0.0",
  "UUID": "com.example.timer",
  "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.timer.counter",
      "Name": "Counter",
      "Icon": "imgs/action-icon",
      "States": [
        {
          "Image": "imgs/action-state"
        }
      ]
    }
  ]
}

Verwende die aktuelle Schema-URL in manifest.json für die Editor-Validierung.

7. Häufige Action-Events

Event	Wofür du es nutzt
onWillAppear	Titel/Bild initialisieren, wenn die Action in einem Profil erscheint
onWillDisappear	Timer stoppen, abmelden, aufräumen
onKeyDown	Sofort auf einen Tastendruck reagieren
onKeyUp	Erst nach dem Loslassen auslösen, nützlich für klickartiges Verhalten
onDialRotate	Drehung des Stream Deck + Dials behandeln
onDialPress	Druck auf die Dial-Taste behandeln
onTouchTap	Interaktionen mit dem Stream Deck + Touchstreifen behandeln

8. Einstellungsmuster

Nutze Einstellungen für Nutzerkonfiguration und kleinen Zustand pro Action.

Gute Einstellungen:

• ausgewähltes Profil oder Ziel,
• API-Basis-URL,
• Anzeigemodus,
• Zähler-/Umschaltzustand,
• nicht geheime IDs.

Schlechte Einstellungen:

• lange Caches,
• private Tokens,
• hochfrequente Telemetrie,
• generierte Dateien, die sich nach dem Packen ändern.

Nutze für Geheimnisse den Anmeldedaten-Speicher des Betriebssystems, einen lokalen Companion-Dienst oder eine explizit nutzerverwaltete Konfiguration außerhalb des verteilbaren Plugins.

9. Debugging

Elgatos SDK unterstützt Node.js-Debugging. Hänge dich in VS Code an den Node-Prozess des Stream Deck Plugins an, während das Plugin läuft.

Das Manifest kann Node-Debugging konfigurieren:

{
  "Nodejs": {
    "Version": "24",
    "Debug": "enabled"
  }
}

Nutze feste Ports nur, wenn nötig:

{
  "Nodejs": {
    "Version": "24",
    "Debug": "--inspect=127.0.0.1:12345"
  }
}

10. Wann JavaScript ausreicht

Reines JavaScript ist akzeptabel, wenn:

• das Plugin ein oder zwei Actions hat,
• die Action-Einstellungen trivial sind,
• kein gemeinsames Domänenmodell existiert,
• du die geringstmögliche Reibung willst.

11. Wann TypeScript sich lohnt

Nutze TypeScript, wenn:

• Actions Einstellungen oder Payload-Modelle teilen,
• das Plugin Tasten und Dials unterstützt,
• ein Property Inspector mit dem Plugin spricht,
• asynchroner Zustand wichtig ist,
• Nutzende auf stabiles Verhalten angewiesen sind.

Für neue Arbeit ist TypeScript der bessere Standard.