Sites entwickeln und bereitstellen

Diese Anleitung richtet sich an externe Entwickler und Agenturen. Sie entwickeln eine Website, einen Shop oder ein Portal in einem lokalen Projektordner und veröffentlichen die Site anschließend im Sites-Katalog. Dafür benötigen Sie weder Zugang zu einem Kunden-Workspace noch Git oder eine CI-Umgebung.

Voraussetzungen

Sie benötigen:

• eine Einladung zum Publisher-Bereich,
• eine aktuelle nucli-Installation,
• einen lokalen Ordner mit editierbaren Sitegenerator-Quellen.

Ein Site Package enthält die vollständigen Quellen, nicht den Build-Ausgang. Build-Verzeichnisse, node_modules, Git-Metadaten, Secrets und lokale Umgebungsdateien werden nicht übernommen.

Publisher und Site anlegen

Der Betreiber lädt Sie zum Publisher-Bereich ein und sendet Ihnen dessen direkte Adresse https://www.schukai.com/de/apps/workspace/sites/publisher. Eine offene Registrierung gibt es während des Piloten nicht. Der öffentliche Katalog zeigt deshalb auch keinen Link für Publisher. Nach dem Einlösen der Einladung melden Sie sich an und legen beim ersten Aufruf eine Publisher-Organisation an, beispielsweise „Nordlicht Digital“.

Erstellen Sie anschließend die Site. Der Eintrag enthält den sichtbaren Namen, die Kategorie, optional eine öffentliche Vorschau-URL sowie eine deutsche und eine englische Zusammenfassung und Beschreibung. Beide Sprachen müssen vollständig sein, bevor Sie eine Version zur Prüfung einreichen können. Nach dem Speichern zeigt der Publisher-Bereich die Store-Site-ID für den späteren CLI-Upload an.

Lokales Projekt vorbereiten

Initialisieren Sie im Projektordner die Paketmetadaten:

nucli sites package init . \
  --publisher nordlicht \
  --site commerce \
  --license MIT

nucli speichert die stabile Paket-ID und die Koordinaten geschützt unter .nucli/site-package.json. Diese Datei bleibt außerhalb des Site Packages. Bewahren Sie sie zusammen mit dem Projekt auf, damit spätere Versionen dieselbe Paket-ID verwenden.

Prüfen Sie die Quellen, bevor Sie eine Version bauen:

nucli sites package validate .

Für Abhängigkeiten ist eine exakte Bindung im Lockfile erforderlich. Versionsbereiche und latest werden abgewiesen. Auch versteckte Pfade, symbolische Links, kollidierende Dateinamen und zu große Dateien führen zu einem Fehler.

Site Package bauen

Erzeugen Sie eine semantisch versionierte ZIP-Datei:

nucli sites package build . \
  --version 1.0.0 \
  --output nordlicht-commerce-1.0.0.zip

Der Befehl erstellt das Manifest, berechnet die Prüfsummen und validiert das fertige Archiv. Eine vorhandene ZIP-Datei lässt sich erneut prüfen:

nucli sites package validate nordlicht-commerce-1.0.0.zip

Entwurf hochladen

Erzeugen Sie bei der Site ein zeitlich begrenztes nucli-Upload-Token. Das Site Package wird immer mit nucli hochgeladen; Git und eine CI-Umgebung sind dafür nicht erforderlich. Übergeben Sie das Token ausschließlich über die Standardeingabe:

nucli --host https://www.schukai.com/apps/workspace/sites \
  sites store upload nordlicht-commerce-1.0.0.zip \
  --site-id <store-site-id> \
  --token-stdin

Leiten Sie das Token in die Standardeingabe und schließen Sie diese anschließend. Das Token gehört weder in die Befehlszeile noch in das Projekt, die ZIP-Datei oder ein Protokoll. Der Store legt den Upload als privaten Entwurf an.

Version einreichen

Prüfen Sie zuerst, ob die deutschen und englischen Metadaten vollständig sind. Öffnen Sie dann den Entwurf im Publisher-Bereich und wählen Sie Zur Prüfung einreichen. Während der Moderation bleibt die Version privat. Nach der Freigabe erscheint sie öffentlich im Katalog und kann in einen leeren Workspace installiert werden.

Eine veröffentlichte Version ist unveränderlich. Korrekturen erhalten eine neue semantische Version und ein neues Site Package.

Git und CI optional nutzen

Git kann Quellstände, Zusammenarbeit und Reviews unterstützen. Eine CI-Pipeline kann denselben Build- und Upload-Ablauf automatisieren. Beides ist optional; der lokale nucli- und Browser-Ablauf bleibt vollständig unterstützt.

Ein öffentliches Repository darf Sitegenerator-Quellen enthalten. Publisher-Tokens, Workspace-Sitzungen, lokale Umgebungsdateien, Build-Ausgaben und exportierte ZIP-Dateien gehören nicht hinein.

Aus einem Workspace exportieren

Wenn Sie bereits in einem Workspace entwickeln und die Berechtigung site:packages:export besitzen, können Sie die dortigen Development-Quellen weiterhin serverseitig exportieren:

nucli --tenant <tenant> sites package export <site-id> \
  --publisher nordlicht \
  --site commerce \
  --version 1.0.0 \
  --license MIT \
  --output nordlicht-commerce-1.0.0.zip

Dieser Komfortweg ist keine Voraussetzung für externe Publisher.

Ein vollständiges Shop-Theme exportieren

Für ein Site Package V2 wählen Sie zusätzlich die gewünschten Fachvorlagen und Gestaltungsressourcen. Die verfügbaren Komponenten zeigt der Sites-Tab oder:

nucli --tenant <tenant> sites package candidates <site-id>

Die Liste enthält standardmäßig 100 Einträge. Mit --limit wählen Sie 1 bis 200 Einträge pro Seite. Gibt die Antwort einen nextCursor zurück, übergeben Sie ihn beim nächsten Aufruf mit --cursor <nextCursor>. Im Sites-Tab laden Sie weitere Einträge über die entsprechende Schaltfläche; Ihre Auswahl bleibt erhalten.

Speichern Sie die ausgewählten Einträge als JSON-Array. Jeder Eintrag enthält einen stabilen paketlokalen key, den kind und die aktuelle resourceId. Branding-Komponenten erhalten außerdem einen targetSlot, den der Importeur später einem bestehenden Zielprofil zuordnet.

[
  {"key": "invoice-de", "kind": "document", "resourceId": "<document-template-id>"},
  {"key": "order-mail-de", "kind": "mail", "resourceId": "<mail-template-id>"}
]

Ergänzen Sie den Exportaufruf um --components-file komponenten.json und beim ersten V2-Export um --package-id <package-uuid>. Die Paket-ID ist unabhängig von der Site-ID und bleibt für spätere Paketversionen gleich. Nach einer Installation kann die gespeicherte Paketidentität weiterverwendet werden.

Der Export liest die aktuellen bearbeitbaren Inhalte einschließlich späterer Änderungen. Er unterstützt Snippets, Beleg- und Mailvorlagen sowie Branding-Assets, Schriften und Themes. Sprachvarianten bleiben eigene Vorlagen; Site-Übersetzungen bleiben unter i18n. Statische Mailanhänge werden mit ihren Dateinamen und Medientypen übernommen. Anhänge mit Verweisen auf konkrete operative Dokumente oder Storage-Objekte blockieren den Export, statt unbemerkt zu fehlen.

Verwenden Sie in den Vorlagen die Platzhalter und Branding-Auflösung des jeweiligen Renderers. Fest in HTML oder Lua eingetragene URLs und IDs bleiben unverändert; der Export schreibt beliebigen Quelltext nicht auf einen anderen Workspace um.

Neue Rechnungsbundles benötigen statisches HTML, damit ihre PDFs bei einer Wiederaufnahme identisch bleiben. Vor der PDF-Erzeugung werden Skripte, Inline-Eventhandler, JavaScript-URLs, eingebettete aktive Dokumente und automatische Navigation abgewiesen. Verwenden Sie für Navigationslinks absolute URLs oder interne Fragmentverweise. Relative Bild- und Schriftpfade bleiben nach dem bestehenden Assetvertrag möglich. Prüfen Sie die gerenderte Rechnung vor der Weitergabe des Themes; der Paketvalidator ersetzt diese Prüfung nicht.

Im lokalen Projekt liegt der Komponentenkatalog unter theme-components/components.json. Der gemeinsame Paketvalidator prüft die referenzierten Dateien und Abhängigkeiten. V2 verlangt die Server-Capability sitepackage.components.v2. Ältere V1-Pakete mit ausschließlich Sitegenerator-Quellen bleiben unterstützt.

V3 mit Profilzuordnungen und Footern

Für eigenständige BrandLogo-Ressourcen, HTML-Footer oder mehrere Profilzuordnungen verwendet das Paket V3 und verlangt sitepackage.theme-components.v3. Sein Katalog enthält components, profileSlots und bindings. Ein Export mit diesen Fähigkeiten lässt sich nicht verlustfrei als V2 ausgeben.

Die aktuellen Profilzuordnungen der ausgewählten Komponenten zeigt der Sites-Tab. Mit der CLI rufen Sie sie über nucli sites package profile-graph <site-id> --components-file komponenten.json ab. Die CLI liefert eine API-Antwort mit meta und data. Speichern Sie nur das Graphobjekt aus data, beispielsweise mit jq '.data' > zuordnungen.json hinter einer Pipe. Prüfen Sie dieses Objekt und übergeben Sie es beim Export mit --bindings-file zuordnungen.json. Sein Fingerprint bindet die Auswahl an den geprüften Stand. Haben sich die Zuordnungen inzwischen geändert, muss die Vorschau erneuert werden. Profilnamen und operative Einstellungen werden nicht als Profilkopien in das Paket übernommen.

Beim Import ordnen profileTargets die Profilplätze und footerTargets die Footerziele vorhandenen Ressourcen zu. decisions enthält die im Plan angezeigten Komponenten- und Bindungsentscheidungen. Große V3-Importoptionen übergeben Sie mit --theme-options-file optionen.json statt --components-file. Die bisherigen Auswahl-Dateien bleiben auf 64 KiB begrenzt; die neuen Graph- und Optionsdateien auf 512 KiB. Verwenden Sie reguläre Dateien; Symlinks, FIFOs und Geräte werden abgewiesen.

Footerkomponenten verweisen auf HTML-Dateien für document oder mail. Pro Kanal ist eine neutrale Variante mit leerer Locale erforderlich. Sprachvarianten werden zuerst exakt, dann über die Grundsprache und zuletzt über die neutrale Vorlage aufgelöst. Eine Quelle darf höchstens 64 KiB, ein gerenderter Footer höchstens 1 MiB groß sein.

Alle Footerquellen zusammen sind auf 100 MiB begrenzt. Jede Verwendung zählt, auch wenn mehrere Sprachvarianten dieselbe Datei nutzen. Komponenten- und Profilmetadaten dürfen pro Prüfschritt ebenfalls höchstens 100 MiB umfassen.

Mit field "Sender.LegalName" geben Sie beispielsweise den aufgelösten Firmennamen aus; label liefert die zugehörige Beschriftung und has prüft, ob ein Feld belegt ist. Tabellen, Spalten und Bedingungen ermöglichen eigene Anordnungen innerhalb der zugelassenen HTML-/CSS-Auswahl. Feldnamen müssen bekannte Literale sein. Schleifen, rekursive Teilvorlagen, Skripte und externe Includes sind nicht zulässig. Erforderliche Felder müssen tatsächlich sichtbar ausgegeben werden. Die Darstellung liegt im Ziel unter FooterDefinition.TemplatePolicy.presentation; Inhalts- und Compliance-Richtlinien bleiben erhalten.

Eigene Dokumentvorlagen binden den Footer über {{.Branding.Footer.HTML}} ein. Full-Layout-Mails verwenden {{.footerHTML}} im HTML-Teil und {{.footerText}} im Textteil. Diese Werte stammen vom Renderer; übergebene Maildaten können sie nicht ersetzen. Der Textteil behält den bisherigen Standardinhalt. Bei einem späteren Fehler der Footerpräsentation verwendet der Renderer den vollständigen Standardfooter.

Innerhalb von .Pages greifen Dokumentvorlagen mit {{$.Branding.Footer.HTML}} auf den Footer zu. Mehrseitige Vorlagen verwenden die bestehenden Attribute data-layout-role, data-layout-page-number und data-layout-page-total; Messvorlagen verwenden data-layout-measurement und data-layout-measure-prototype. Pro Seite oder zugelassenem Messprototyp darf das Fragment höchstens einmal erscheinen. Im sichtbaren Dokument muss mindestens ein Footer vorhanden sein. Indirekte Zugriffe auf reservierte Footerfelder über Aliase, index oder Pipelines werden abgewiesen.

Die Vorabprüfung erkennt direkte Ausblendungen und unsichtbare HTML-Container, berechnet aber keine allgemeine CSS-Kaskade. Prüfen Sie das Zusammenspiel mit den Stylesheets der Dokument- oder Mailvorlage deshalb auch in der Vorschau.

Vor dem Import werden auch bestehende Profile geprüft, die denselben Footer verwenden. Die Prüfung verarbeitet höchstens 500 Footerdefinitionen, 500 Profile und 500 effektive aktive Vorlagen je Kanal sowie insgesamt 2.000 Kombinationen aus Profil, Sprache und Dokumenttyp. Vorlagenquellen dürfen je Kanal zusammen höchstens 100 MiB umfassen. Ein überschrittener Grenzwert blockiert den Import.

Der technische Bereinigungsbeleg ist auf 4 MiB begrenzt. Lange Paketpfade und viele vorhandene leere Verzeichnisse können diese Grenze erreichen, auch wenn die Dateien klein sind. Der Import prüft das Budget vor der Vorbereitung und dem Quellenwechsel.

Statische Mailanhänge sind auf 32 Stück und insgesamt 25 MiB decodierte Daten je Mail begrenzt. Über alle Mailkomponenten eines Pakets gilt eine Grenze von 100 MiB; die einzelne Datei bleibt auf 10 MiB begrenzt. Jeder Verweis zählt, auch wenn mehrere Anhänge dieselbe Paketdatei verwenden.

Prüfung

Die Veröffentlichung ist vorbereitet, wenn:

• nucli sites package validate ohne Fehler endet,
• der Upload als privater Entwurf im Publisher-Bereich erscheint,
• Koordinate und Version im Entwurf dem lokalen Projekt entsprechen.

Nach der Moderation zeigt der öffentliche Katalog die Site und ihre freigegebene Version.

Grenzen der ersten Version

Der Pilot unterstützt kostenlose öffentliche Sites. Verkauf, Abrechnung, Auszahlungen, automatische Updates installierter Sites, eine offene Publisher-Registrierung und Installationen in bereits gefüllte Sites gehören nicht zu diesem Vertrag.