Lokal entwickeln und mit hcms deploy hochschieben
Eigene Blöcke auf dem eigenen Gerät programmieren, selbst oder mit einem KI-Programmierassistenten, und mit einem Befehl auf eine gehostete Website schieben, samt Variablen und Versionen.
Worum es geht
Für gewöhnliche Seiten brauchen Sie keinen Code: Sie bauen sie im visuellen Editor. Brauchen Sie einen Baustein, den es nicht gibt, etwa eine Weinkarte mit Filter, programmieren Sie ihn auf Ihrem Gerät und schieben ihn mit dem Befehl hcms deploy auf die Website, die Scorebase betreibt. Danach steht der eigene Block sofort in der Leiste des Editors, und Redaktion und Agentur stellen Felder, Stile und Inhalte dort ein wie bei jedem anderen Baustein.
Ihr Code läuft in einer eigenen, abgeschotteten Umgebung, nie zusammen mit Scorebase oder mit anderen Kundinnen und Kunden.
Wichtig: Eigener Code geht nur unter einer eigenen Domain online. Hochgeschoben und als Vorschau geprüft werden kann er vorher, live schalten lässt er sich erst, wenn eine eigene Domain verbunden ist. Unter der Standardadresse läuft nur die gemeinsame Auslieferung ohne eigenen Code.
Voraussetzungen
- Eine gehostete Website mit dem Zusatz-Abo Hosting und dem Zusatz Eigener Code. Ohne ihn steht dort „Eigener Website-Code gehört zum Zusatz Eigener Code. Buchen Sie ihn, um Code hochzuladen.“
- Das Recht Eigenen Website-Code hochladen (Bereich Websites). Ohne es steht „Für eigenen Website-Code fehlt Ihnen die Berechtigung.“
- Node.js ab Version 20 und npm auf Ihrem Gerät.
- Eine verbundene eigene Domain, sobald die Version live gehen soll.
Der Weg in vier Schritten
Öffnen Sie in Sites die Website und klicken Sie auf Lokal entwickeln. Die Seite führt durch dieselben Schritte und zeigt die Befehle zum Kopieren.
1. Projekt holen
npx @kailua-packages/headless-cli init meine-website --hosting scorebase \
--url https://<ihre-organisation>.scorebase.ch/headless \
--token <Entwicklungsschlüssel>Das lädt den Starter mit allen Scorebase-Bausteinen, die eigenen Blöcke der Umgebung, auf die die Website zeigt, und die Anleitung für KI-Programmierassistenten. Die Einrichtung ist dieselbe wie bei Eigene Website anbinden.
Hinweis zum Aufruf: Der Befehl heisst
hcmsund gehört zum Paket@kailua-packages/headless-cli. Rufen Sie ihn in einem leeren Ordner immer über den Paketnamen auf, wie oben gezeigt, nie mitnpx hcms: Das würde ein anderes Paket gleichen Namens laden. Im fertigen Projekt stehthcmsin den Skripten vonpackage.json, dort genügt der kurze Name.
Den Entwicklungsschlüssel erstellen Sie auf der Seite Lokal entwickeln mit Neuen Schlüssel erstellen. Geben Sie dem Gerät eine Bezeichnung, zum Beispiel „Laptop von …“. Der Schlüssel wird nur einmal angezeigt und liegt danach nur auf dem Gerät, in .env.local. Er darf Seiten und Inhalte lesen und Vorschau-Versionen hochschieben. Ob er auch ohne Rückfrage live schalten darf, hängt von den Rechten der Person ab, die ihn erstellt hat. Anlegen dürfen ihn nur Personen mit dem Recht, Website-Code hochzuladen. Widerrufen sperrt einen Schlüssel sofort, etwa bei einem verlorenen Gerät.
2. Lokal starten
npm run devDie Website läuft auf Ihrem Gerät mit den echten Seiten und Inhalten aus Sites. Lokal wird nur gelesen, nichts verändert.
3. Block bauen
Legen Sie den Block mit Code, Feldern und Vorschau an, oder geben Sie einem KI-Programmierassistenten den Auftrag. Das Projekt bringt dafür eine Anleitung mit, die der Assistent beim Start liest. Ein Beispiel mit Claude Code, das hier nur für ein Werkzeug stehen soll, das Sie selbst einsetzen:
Baue einen Block „Weinkarte“ mit Filter nach Region und Preis.
Halte dich an die Anleitung im Projekt, nutze die vorhandenen Bausteine
und lege die Felder so an, dass ich sie im Inspektor des Editors einstelle.
Starte danach die Prüfung und die Tests.Jeder Block braucht seinen Code, die Beschreibung seiner Felder (damit der Inspektor sie zeigt) und einen Eintrag in components/blocks/registry.tsx. Ohne diese Datei bricht der Befehl ab.
4. Hochschieben
npx @kailua-packages/headless-cli deployIm Folgenden steht kurz hcms deploy für diesen Aufruf. Wo das Paket im Projekt installiert ist, genügt in einem Skript von package.json der kurze Name hcms.
hcms deploy prüft die Blöcke, baut lokal, packt ein Archiv und lädt es hoch. Scheitert der Bau lokal, geht nichts ins Netz. Dann baut Scorebase eine eigene, abgeschottete Version nur für diese Umgebung und zeigt zuerst eine Vorschau. Der Befehl fragt: „Version N live schalten? (j/N)“. Nur mit dem passenden Recht darf er live schalten; sonst endet er mit „bereit, live schaltet eine Person in Sites“.
Eine Beispielausgabe:
Blöcke geprüft: 1 eigene, alle Scorebase-Bausteine aktuell
Typen und Tests grün
Version 7 gebaut, abgeschottet für „Weingut Beispiel“
Vorschau: https://…
Version 7 live schalten? (j/N)Nützliche Optionen:
| Option | Wirkung |
|---|---|
--dry-run |
Prüft, baut und packt lokal, ohne etwas ins Netz zu schicken |
--ja |
Schaltet ohne Rückfrage live, auch ohne Terminal |
--liste |
Zeigt frühere Versionen |
--zurueck <Version> |
Stellt eine frühere Version wieder her, ohne neuen Bau |
--herunterladen [Version] |
Lädt den Quelltext einer Version |
Was hochgeht und was nie
| Geht hoch | Geht nie hoch |
|---|---|
| Code der Website: Blöcke, Layout, Stile | Seiten und Inhalte: Sie bleiben in Sites, der Befehl überschreibt nichts aus dem visuellen Editor |
| Beschreibung der Felder eigener Blöcke | Zugangsdaten: nur der Schlüssel bleibt lokal |
Vor dem Hochladen sucht der Befehl im Archiv nach Zugangsdaten. Dateien wie .env* und .npmrc, Editor-Einstellungen mit Schlüsseln und Schlüssel von Scorebase im Code stoppen den Vorgang. Die Prüfung arbeitet nach Mustern: Eine Datei mit anderem Namen, etwa credentials.json, würde sie nicht erkennen. Legen Sie deshalb nie Zugangsdaten ins Projekt, egal unter welchem Namen. Für Werte, die Ihr Code zur Laufzeit braucht, gibt es eigene Variablen.
Eigene Variablen
Auf der Seite Bereitstellungen der Website hinterlegen Sie unter Eigene Variablen Werte, die Ihr Code zur Laufzeit liest, etwa die Adresse eines Zahlungsdienstes.
- Der Name besteht aus Grossbuchstaben, Ziffern und Unterstrich und beginnt mit einem Buchstaben, höchstens 64 Zeichen. Der Wert hat höchstens 4096 Zeichen.
- Werte werden verschlüsselt gespeichert und nach dem Speichern nicht mehr angezeigt.
- Änderungen gelten ab der nächsten Bereitstellung.
- Sperrliste nach Mustern: Namen, die Scorebase selbst braucht (etwa die der Website-Schlüssel), und Namen nach den Mustern für Datenbank-, Speicher-, Cloud- und Plattform-Zugänge sind gesperrt, ebenso Werte, die einem Geheimnis der Plattform gleichen. Sites meldet dann „Dieser Name ist für Scorebase reserviert.“ Ihre Website bekommt die Schlüssel, die sie zum Lesen braucht, von Scorebase automatisch.
- Im Protokoll einer Bereitstellung erscheinen Werte eigener Variablen nicht im Klartext. Schreiben Sie sie dennoch nicht in Ausgaben Ihres Codes.
Versionen, Vorschau und Wiederherstellen
Die Seite Bereitstellungen des Website-Codes zeigt jede Version mit Version, Was sich geändert hat, Von, Zeit und Zustand (Hochgeladen, Wird gebaut, Bereit, Live, Frühere Version, Fehlgeschlagen).
- Live schalten setzt eine bereite Version live. Das geht nur mit eigener Domain.
- Wiederherstellen schaltet eine frühere Version wieder live, ohne neuen Bau. Seiten und Inhalte ändern sich dabei nicht.
- Quelltext herunterladen liefert den Code einer Version.
- Das Laufzeit-Protokoll zeigt Meldungen der laufenden Website.
- Zurück zur gemeinsamen Auslieferung lässt die Website wieder mit den Bausteinen von Scorebase laufen. Ihr eigener Code bleibt gespeichert. Das geht nicht, solange Seiten eigene Blöcke aus Code verwenden: Entfernen Sie diese zuerst aus den Seiten.
- Die Vorschau-Adresse einer Version ist zum Prüfen gedacht und bleibt nur kurze Zeit erreichbar.
Die Konfiguration der Auslieferung
Ihre eigene Konfiguration der Auslieferung wird durch unsere ersetzt. Das betrifft jede Datei im Projekt, die Einstellungen zur Auslieferung enthält: Zeitpläne (Crons), Weiterleitungen und Einstellungen zu Funktionen, die Sie darin eintragen, gelten nicht. Weiterleitungen pflegen Sie stattdessen in Sites unter Weiterleitungen. Für Aufgaben nach Zeitplan nutzen Sie ein System ausserhalb der Website, das einen Aufruf auslöst.
Grenzen
- Die Grösse und die Zahl der Dateien im Archiv sind begrenzt. Zu grosse Archive weist der Befehl ab.
- Es gibt ein Tageslimit für Bauten, damit kein Fehler in einer Schleife die Plattform belastet. Bei Erreichen steht „Für heute sind keine weiteren Bereitstellungen möglich. Morgen geht es wieder.“ Umstellen und Neubau zählen mit.
- Ein Bau darf höchstens 10 Minuten dauern.
- Die Bibliotheken aus Ihrem Lockfile werden verwendet. Ein Lockfile (zum Beispiel
package-lock.json) ist Pflicht. - Der Abruf eigener Bereitstellungen zählt in Ihr Kontingent, siehe Kontingent, Laufzeit und Sperre.
Wenn etwas nicht klappt
| Symptom | Ursache | Lösung |
|---|---|---|
| „Das Archiv enthält Zugangsdaten oder einen Schlüssel.“ | Eine Datei im Projekt enthält einen Schlüssel | Datei entfernen, Schlüssel in eine eigene Variable legen |
| „Die Datei components/blocks/registry.tsx fehlt.“ | Der Aufbau des Projekts ist verändert | Datei wiederherstellen |
| „Das Lockfile fehlt.“ | Abhängigkeiten sind nicht festgeschrieben | npm install ausführen und das Lockfile einchecken |
| „Ihre Seiten verwenden Blöcke, für die der Code fehlt.“ | Ein Block ist auf Seiten, aber nicht im Code | Block in den Code aufnehmen oder von den Seiten entfernen |
| „Eigener Code geht nur mit einer eigenen Domain online.“ | Die Website hat keine eigene Domain | Domain verbinden |
| „Der Bau ist fehlgeschlagen.“ oder „länger als 10 Minuten“ | Fehler im Code oder zu aufwendiger Bau | Lokal mit npm run build nachvollziehen |
| „Der Dienst ist gerade nicht erreichbar. Die Website bleibt unverändert.“ | Vorübergehende Störung | Später erneut hochschieben |
| Der Block fehlt in der Leiste des Editors | Die Version ist noch nicht live oder die Felder sind nicht beschrieben | Zustand prüfen, Version live schalten |