Skip to Content
CubyStudio-Integration

Studio-Integration

Cuby kann als eingebettete Komponente im ProcessCube® Studio (oder anderen Host-Anwendungen) betrieben werden. Dafür bietet es einen eigenen /apps-Namespace ohne Header und Footer sowie eine PostMessage-basierte Authentifizierung.

/apps-Namespace

Alle Seiten sind unter dem /apps-Prefix als Standalone-Layout verfügbar — ohne Header und Footer, optimiert für die iframe-Einbettung:

RouteSeite
/appsMeine Apps (installierte Produkte)
/apps/product/:idProdukt-Detail
/apps/marketplaceMarketplace
/apps/setup/products/:id/configPlugin-Konfiguration

Zwei Layout-Modi

PostMessage-Auth-Flow

Die Authentifizierung zwischen Studio und eingebettetem Cuby-iframe erfolgt über window.postMessage:

Der Auth-Hook im Frontend (usePostMessageAuth.js) empfängt den Token automatisch und tauscht ihn gegen ein Session Cookie.

Ansicht steuern

Das Studio kann die Ansicht des eingebetteten Cuby über PostMessage-Events steuern:

MessageWirkung
"fullsize"Vollbild-Modus (maximale Fläche)
"normal"Standard-Ansicht

Theme-Steuerung

Das Theme kann per URL-Parameter erzwungen werden, um es an das Host-System anzupassen:

http://localhost:3847/apps?theme=dark
http://localhost:3847/apps?theme=light

Ohne Parameter wird die Betriebssystem-Einstellung verwendet.

React-Shims

Plugin-Komponenten (config-component.js, detail-component.js) nutzen React-Shims, um die gleiche React-Instanz wie die Host-Anwendung zu verwenden. Das verhindert Konflikte durch mehrere React-Versionen:

EndpunktModul
/api/shim/react.jsReact (alle Hooks und APIs)
/api/shim/react-jsx-runtime.jsJSX Runtime (jsx, jsxs, Fragment)
/api/shim/react-dom.jsReactDOM (createPortal, createRoot, etc.)

Plugin-Komponenten importieren React über diese Shims statt über eigene node_modules.

Embedding-Beispiel

<!-- Im Studio oder einer anderen Host-Anwendung -->
<iframe
  id="cuby-frame"
  src="http://localhost:3847/apps"
  style="width: 100%; height: 100%; border: none;"
></iframe>
 
<script>
  const frame = document.getElementById('cuby-frame');
 
  // 1. Auth-Token holen
  const res = await fetch('http://localhost:3847/api/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ apiKey: 'DEIN_API_KEY' })
  });
  const { token } = await res.json();
 
  // 2. Token an iframe senden
  frame.contentWindow.postMessage(
    { type: 'cuby:auth', token },
    'http://localhost:3847'
  );
</script>

Regeln für neue Seiten

Beim Hinzufügen neuer Seiten im Frontend:

  • Jede Seite, die von /apps aus erreichbar ist, braucht eine Route unter /apps/...
  • Keine hardcoded Zurück-Pfade — Komponenten erhalten backPath und basePath als Props
  • Navigation-Pfade immer mit basePath prefixen
  • returnTo in location.state für Seiten, die von verschiedenen Stellen aufgerufen werden

Weiterführend

AuthentifizierungSub-Cuby Federation