Zum Inhalt springen
Penates Penates

Browser-Preview

Was es ist

Die Browser-Preview ist ein Split-Panel rechts neben dem Terminal, das einen laufenden lokalen Dev-Server (Vite, Next.js oder jeden anderen HTTP-Server) in einem iframe einbettet. Da der Remote-Browser localhost nicht direkt erreichen kann, reverse-proxied der Hub den Dev-Server über einen festen Host: preview.<PREVIEW_DOMAIN>.

Zu einer Zeit ist nur ein Preview-Port aktiv. Der Hub scannt lauschende Ports via lsof und listet sie in einer Combobox auf; man wählt einen aus. Der Proxy behandelt sowohl HTTP- als auch WebSocket-Verbindungen, sodass Hot-Module-Replacement (HMR) durch das Panel funktioniert.

Das Feature ist inaktiv, wenn PREVIEW_DOMAIN nicht in .env gesetzt ist. Es erfordert einen einzelnen DNS-CNAME-Eintrag preview, der auf deinen Cloudflare-Tunnel zeigt, sowie einen Public Hostname, der auf localhost:<PORT> zeigt. Kein Wildcard-DNS-Eintrag ist nötig; das Universal-SSL-Zertifikat von Cloudflare (*.<domain>) deckt die Subdomain automatisch ab.

Warum / wann

Das Preview-Panel macht es überflüssig, einen separaten Browser-Tab zu öffnen, wenn man an einem Web-Projekt in einer Coding-Session iteriert. Der Coding-Agent ändert Dateien, HMR aktualisiert die Preview, und das Ergebnis ist im selben Fenster sichtbar.

Wie nutzen

  • Aktivieren: PREVIEW_DOMAIN=yourdomain.com in .env eintragen und den Hub neu starten. Das Cloudflare-Setup, das setup.sh ausgibt, befolgen (ein DNS-CNAME preview, ein Public Hostname, Host zur Access-App hinzufügen).
  • Panel öffnen: Preview-Toggle auf der Session-Karte klicken. Das Panel belegt denselben Slot wie das Repo-Panel; eines öffnen schließt das andere.
  • Port wählen: Die Combobox listet aktuell lauschende Ports auf (Hub-Port und Ports unter 1024 werden herausgefiltert). Den Port des Dev-Servers wählen. Der Hub proxied diesen Port sofort.
  • HMR: Für die meisten Dev-Server ist keine zusätzliche Konfiguration nötig. Wenn der Dev-Server den WebSocket-Origin prüft, server.hmr.clientPort: 443 in seiner Konfiguration setzen.

Grenzen

Nur eine Preview ist gleichzeitig aktiv. Apps mit hartkodierten Origin-URLs können fehlrouten, da der Hub keine Response-Bodies umschreibt. HMR-Clients, die den geproxieten Origin ablehnen, benötigen server.hmr.clientPort: 443 (oder äquivalent) in der Dev-Projekt-Konfiguration. Das Feature benötigt einen funktionierenden Cloudflare-Tunnel mit konfiguriertem preview-CNAME und Public Hostname; es funktioniert nicht in einem lokalen Netzwerk ohne diese Voraussetzungen. Das iOS-Simulator-Panel teilt denselben Slot, daher können Web-Preview und Simulator nicht gleichzeitig geöffnet sein.