WebStorm-Plugin für React UI-Kit-Verträge

React Component Contract Guard: WebStorm-Plugin gegen UI-Kit-Abdriften

In großen Frontend-Projekten driftet das UI-Kit auseinander: zwischen TypeScript-Typen, tatsächlicher JSX-Nutzung und Storybook-Stories. Komponenten mit Dutzenden Einsatzorten sammeln ungedokumentierte Props, veraltete Stories und versteckte Abhängigkeiten an. Standard-TypeScript fängt Syntaxfehler, aber die großen Fragen bleiben: Ist der Mismatch isoliert oder systemisch? Wie viele Stellen betrifft eine Prop-Änderung? Spiegelt Storybook die aktuelle API wider?

Component Contract Guard löst das mit einem Contract-Analyzer und WebStorm-Plugin. Das Tool baut ein Komponenten-Modell aus drei Quellen auf: TypeScript-Contracts, JSX-Nutzungen und Storybook-args – und hebt Abweichungen direkt im Editor hervor.

Hier ein typisches Komponenten-Beispiel:

type ButtonProps = {
  label: string;
  variant?: "primary" | "secondary";
  icon?: React.ReactNode;
};

export function Button({ label, variant = "primary", icon }: ButtonProps) {
  return (
    <button data-variant={variant}>
      {icon}
      {label}
    </button>
  );
}

Aber im Projekt sieht man:

<Button variant="primary" tone="loud" />
<Card title="Health" variant="ghost" />

Storybook referenziert vielleicht nicht existierende mystery: true.

Architektur: CLI-Analyzer + IDE-Plugin

Das Projekt teilt sich in zwei Schichten für Unabhängigkeit und Wiederverwendbarkeit:

• CLI-Analyzer (TypeScript): Lädt tsconfig.json, erstellt ein TypeScript-Programm, extrahiert Prop-Contracts aus TSX-Exports, sammelt JSX-Nutzungen, parst CSF-Storybook.

• WebStorm-Plugin (Kotlin): Führt CLI aus, parst JSON-Ergebnisse, zeigt Inline-Hinweise, Unterstreichungen, Tooltips, Datei-Zusammenfassungen und Impact-Reports.

Diese Trennung erlaubt CLI-Nutzung in CI, vermeidet Duplikate und erleichtert Ports zu anderen IDEs.

Die Analyse läuft in drei Phasen:

• Contract-Sammlung: Extrahiert Prop-Namen, Typen, Required-Status, Defaults, JSDoc. Behandelt Destructuring mit Defaults.

• Usage-Sammlung: JSX-Positionen, übergebene Props, Spread-Expressions (mit vorsichtigen Warnungen).

• Storybook-Parsing: meta.args, argTypes, Story-Objekte.

Analyzer-Signale und Warnungen

Das Plugin erzeugt präzise Warnungen:

• Unbekannte Prop übergeben (z. B. tone bei Button).
• Fehlende required Prop (z. B. label).
• Storybook referenziert unbekannte Prop (mystery).
• Contract-Prop nicht in Storybook widergespiegelt.
• Ungenutzte Prop weder im Code noch in Stories.

Pro Prop berechnet es den Impact:

• Anzahl Code-Nutzungen.
• Anzahl Story-Nutzungen.
• Änderungsrisiko (bewertet nach Häufigkeit).

Das unterscheidet lokale Anpassungen von public-API-Migrationen.

Warnungsbeispiele:

• Unbekannte Prop "tone" an Button übergeben
• Button fehlt required Props: label
• Story BrokenStory referenziert unbekannte Prop "mystery" für Button
• Button.icon nicht in Storybook args/argTypes dokumentiert

WebStorm-Integration: Inline-Signale

Das Plugin triggert bei Datei-Öffnen/Speichern: CLI-Scan → JSON → UI-Elemente.

Anzeige-Kanäle:

• Inline-Badges über problematischen Zeilen.
• Wellen-Unterstreichungen für JSX-Bereiche.
• Hover-Tooltips mit Details und Fixes.
• Datei-Zusammenfassung oben.
• Tool-Fenster für Projekt-Übersicht und Prop-Impact.

Der Ablauf integriert nahtlos in den Editor – konfliktfrei.

Ziel-Use-Cases

Das Tool glänzt bei:

• UI-Kits und Design-Systemen.
• Internen Komponenten-Bibliotheken.
• Großen Monorepos mit 50+ Komponenten.
• Projekten, wo Storybook als Dokumentations-Contract dient.

Bei kleinen Projekten (3–5 Komponenten) reicht manuelle Prüfung; Drift entsteht bei Skalierung.

Kern-Highlights

• Control Object: Kein AST oder Files, sondern Contracts als Verknüpfung zwischen Typen/Nutzungen/Docs/Impact.
• TypeScript Compiler API: Präzises Prop-Parsing ohne Abkürzungen.
• Spread-Behandlung: Vorsichtige Warnungen für dynamische Props.
• Impact-Bewertung: Quantitative Risikoabschätzung für Migrationen.
• IDE-Integration: Inline-Signale als native Workflow-Elemente, kein externes CLI.

Weiterentwicklung

Das MVP fokussiert Kern-Analyse. Roadmap:

• Breaking-Change-Erkennung über Versionen.
• Auto-Migration-Prop-Vorschläge.
• CI/PR-Integration.
• Wrapper-Komponenten-Support.
• Tiefere Storybook-Analyse.
• Impact-Gruppierung nach Projekt-Layern.

— Editorial Team