Voraussetzungen und Installation

Voraussetzungen

Für die Entwicklung von WebUI Runtime-Anwendungen wird die folgende Software benötigt:


Software	Unterstützte Version
Node.js®	22 LTS
npm	10 oder höher
IDE	Visual Studio Code empfohlen, aber jeder Code-Editor ist geeignet
KI-Codierassistent (optional)	Claude Code, GitHub Copilot oder ähnliche Tools können die Entwicklung beschleunigen

Die allgemeinen WinCC OA-Softwareanforderungen finden Sie unter Software-Voraussetzungen.

Laufzeitvoraussetzungen

Zum Betrieb einer bereitgestellten WebUI Runtime-Anwendung werden die folgenden Komponenten benötigt:


Anforderung	Details
WinCC OA	Version 3.21 oder höher
webserver.js	Aktiviert mit WebSocket-Unterstützung
Browser	Moderner Browser mit Unterstützung für ES-Module und Import Maps, Chrome empfohlen (siehe Softwarevoraussetzungen)

Installation

Stellen Sie sicher, dass Node.js® 22 LTS und npm 10 oder höher installiert sind. Ein WinCC OA-Projekt mit aktiviertem webserver.js muss verfügbar sein.

Dateibaum des WebUI Runtime Engineering-Workspace — Abbildung 1. Workspace-Struktur der WebUI Runtime

Erstellen Sie ein neues leeres Verzeichnis als Workspace und wechseln Sie in dieses.
Initialisieren Sie den Workspace, indem Sie das Paket @wincc-oa/webui-runtime installieren und die Init-Skripte ausführen:
```
npm install @wincc-oa/webui-runtime
npx webui-runtime-init
npm install --save-dev --no-audit --no-fund
npm run init:oa-data
```
Starten Sie den Entwicklungsserver, indem Sie npm start ausführen. Der Entwicklungsserver startet unter http://127.0.0.1:4300/ und leitet WebSocket- und REST-Anfragen an das WinCC OA-Backend weiter. Das Proxy-Ziel ist standardmäßig https://localhost. Um den Entwicklungsserver auf ein anderes WinCC OA-Backend zu richten, setzen Sie die Umgebungsvariable BASE_URL vor dem Ausführen von npm start. Der Wert wird in vite.shared.ts gelesen und hat Vorrang vor dem Standardwert.
- PowerShell
- CMD
- Git Bash / Linux
```
$env:BASE_URL="https://my-host:8843"; npm start
```
```
set BASE_URL=https://my-host:8843 && npm start
```
```
export BASE_URL="https://my-host:8843" && npm start
```
Öffnen Sie einen Browser und überprüfen Sie die Einrichtung, indem Sie folgende Adresse aufrufen:
```
http://127.0.0.1:4300/
```

Der Entwicklungsserver läuft nun und ist mit dem WinCC OA-Backend verbunden. Änderungen an Quelldateien lösen automatische Seitenaktualisierungen aus.

Wichtig:

Wenn Sie den Workspace mit npm install @wincc-oa/webui-runtime initialisieren, erhalten Sie einen Snapshot des Workspace in seiner aktuellen Form. Wenn eine neue Version der WebUI Runtime veröffentlicht wird und sich Workspace-Dateien geändert haben, gibt es keinen automatischen Merge — Sie müssen einen neuen Workspace neben dem bestehenden einrichten und die Dateien manuell vergleichen. Um den Migrationsaufwand zu minimieren, vermeiden Sie nach Möglichkeit Änderungen an den Original-Workspace-Dateien oder dokumentieren Sie alle vorgenommenen Änderungen.

Build und Deployment

Um die Anwendung zu erstellen und in einem WinCC OA-Projekt bereitzustellen, setzen Sie die Umgebungsvariable OUT_DIR auf das Verzeichnis data/dashboard-wc/ des Zielprojekts und führen Sie den Build-Befehl aus.

PowerShell
CMD
Git Bash

$env:OUT_DIR="D:\WinCC_OA_Proj\3_21\MyProject\data\dashboard-wc"; npm run build

set OUT_DIR=D:\WinCC_OA_Proj\3_21\MyProject\data\dashboard-wc && npm run build

export OUT_DIR="D:\WinCC_OA_Proj\3_21\MyProject\data\dashboard-wc" && npm run build

Die Build-Pipeline führt die folgenden Phasen aus:

1. Ausgabeverzeichnis bereinigen
2. Gemeinsame Bundle-Einträge generieren
3. Gemeinsame Bundles erstellen (lit.js, ix.js, rxjs.js, wui.js)
4. Anwendung erstellen (index.html, Standalone-Seiten, Assets, Service Worker)

Öffnen Sie nach Abschluss des Builds die URL https://host:port/data/dashboard-wc/index.html in einem Browser und ersetzen Sie host und port durch die Adresse des webserver.js.

Anmerkung:

Für eine schnellere Iteration während der Entwicklung verwenden Sie npm run build:pages, um nur die Standalone-Seiten neu zu erstellen, ohne gemeinsame Bundles oder Assets neu zu erstellen.