E EmDash CMS Everything Guides, use cases, plugins, templates
Deutsch

Bundling und Veröffentlichung

Auf dieser Seite

Sobald Ihr Sandbox-Plugin funktioniert, veröffentlichen Sie es, damit andere Websites es installieren können. Die Veröffentlichung ist nur für Sandbox-Plugins vorgesehen – native Plugins werden über npm verteilt.

Wenn Sie veröffentlichen, zeichnet die CLI die Version in Ihrem eigenen Atmosphere account auf. Sie hosten das tarball selbst – als GitHub Release Asset, R2, S3 oder eine beliebige öffentliche URL – und das Registry speichert einen Link darauf.

Voraussetzungen

  • Eine gültige emdash-plugin.jsonc mit slug, publisher, license, einem Autor (author oder authors) und einem Sicherheitskontakt (security oder securityContacts). Führen Sie emdash-plugin validate aus, um dies zu bestätigen.
  • Eine version (in package.json oder im manifest für registry-only Plugins).
  • Ein Atmosphere account zum Veröffentlichen.

Ihr Atmosphere account

Sie veröffentlichen unter einem Atmosphere account: einer portablen, benutzereigenen Identität, die über Bluesky und andere Apps im AT Protocol-Netzwerk verwendet wird. Ein Account ist Ihr einziger Login im gesamten Netzwerk, mit demselben @handle überall, und Ihre Identität und Daten sind nicht an eine einzelne App gebunden. EmDash verwendet diesen Account als Ihre Publisher-Identität: Jede Version, die Sie veröffentlichen, ist ein Datensatz in Ihrem eigenen Account, unter Ihrem Namen signiert.

EmDash verwendet dieselben Atmosphere accounts wie sein Atmosphere login für Websites.

Einen bestehenden Account verwenden

Wenn Sie bereits einen Bluesky-Account oder einen anderen Atmosphere account haben, melden Sie sich mit dessen Handle an:

emdash-plugin login alice.bsky.social

Dies öffnet die Anmeldeseite Ihres Account-Anbieters im Browser. EmDash sieht Ihr Passwort nie. emdash-plugin whoami listet Ihre gespeicherten Sitzungen auf; emdash-plugin switch <did> wechselt die aktive Sitzung.

Für einen Account registrieren

Wenn Sie noch keinen Atmosphere account haben, erstellen Sie einen über einen beliebigen Anbieter und führen Sie dann emdash-plugin login <your-handle> aus. Ihre Optionen:

  • Eine App wie Bluesky. Die Registrierung bei Bluesky erstellt einen von Bluesky gehosteten Atmosphere account. Dies ist der schnellste Weg.
  • Ein unabhängiger Anbieter. Community-betriebene oder datenschutzorientierte Account-Hosts. Durchsuchen Sie Optionen unter atmosphereaccount.com.
  • Selbst gehostet. Betreiben Sie Ihren eigenen Anbieter für volle Kontrolle über Ihre Identität und Daten.

Welche Option Sie auch wählen, der @handle dieses Accounts ist das, was Sie an emdash-plugin login übergeben, und die DID des Accounts ist das, was Sie als publisher in Ihrem manifest festlegen.

Drei Schritte

Die folgenden Befehle melden Sie an, erstellen ein tarball und veröffentlichen eine Version, die auf das gehostete tarball verweist:

emdash-plugin login                     # falls noch nicht angemeldet
emdash-plugin bundle                    # erzeugt dist/<slug>-<version>.tar.gz
# laden Sie das tarball zu einer öffentlichen URL hoch, dann:
emdash-plugin publish --url https://your-host/<slug>-<version>.tar.gz

bundle gibt die nächsten zwei Schritte aus, wenn es fertig ist, einschließlich des --url-Aufrufs, sodass Sie sich die Form nicht merken müssen.

Bundle

bundle führt build aus, validiert, sammelt Assets und erstellt ein tarball. Innerhalb des tarballs wird plugin.mjs als backend.js gepackt (der Dateiname, den das Registry erwartet).

Der Befehl akzeptiert die folgenden Flags:

emdash-plugin bundle [--dir <path>] [--out-dir|-o <path>] [--validate-only]
FlagStandardBeschreibung
--dirAktuelles VerzeichnisPlugin-Quellverzeichnis.
--out-dir, -odistAusgabeverzeichnis für das tarball.
--validate-onlyfalseTarball überspringen, aber trotzdem dist/-Artefakte erzeugen.

Tarball-Inhalte

DateiErforderlichBeschreibung
manifest.jsonJaGeneriertes manifest: id, version, capabilities, hosts und die aus Ihrer Quelle gelesenen hooks und routes. Sie pflegen dies nicht manuell.
backend.jsJaDie gebaute, selbstständige Runtime-Datei (dist/plugin.mjs).
README.mdNeinPlugin-Dokumentation.
icon.pngNein256×256 PNG.
screenshots/NeinBis zu 5, max 1920×1080.

Validierung

bundle (und --validate-only) prüfen:

  • Größenbeschränkungen (RFC 0001, dekomprimiert): gesamt ≤ 256 KB, pro Datei ≤ 128 KB, ≤ 20 Dateien. Das gzippte tarball ist ein Bruchteil davon.
  • Keine Node built-ins in backend.js — Sandbox-Code kann fs, path, child_process usw. nicht importieren. Verwenden Sie Web APIs oder verschieben Sie diese Logik in ein natives Plugin.
  • Capability-Vernünftigkeit — Namen müssen im anerkannten Set sein.
  • Trust-contract-Kohärenz — die network:request / allowedHosts Kreuzregeln aus dem manifest.
  • Asset-Limits — icon 256×256, ≤ 5 Screenshots bei ≤ 1920×1080.

Um das tarball vor der Veröffentlichung zu inspizieren, listen Sie seinen Inhalt auf:

emdash-plugin bundle
tar tzf dist/my-plugin-1.1.0.tar.gz

Publish

Die Veröffentlichung schreibt den Versionsdatensatz. Das tarball muss bereits unter einer öffentlichen URL gehostet sein:

emdash-plugin publish --url <hosted-tarball-url>

--url ist erforderlich: Es ist der Ort, an dem die Bytes des Plugins liegen, und der Registry-Datensatz verweist darauf. Um zu überprüfen, ob die gehostete URL genau die Bytes bereitstellt, die Sie erstellt haben, bevor der Datensatz geschrieben wird, übergeben Sie --local:

emdash-plugin publish --url https://your-host/foo-1.0.0.tar.gz --local dist/foo-1.0.0.tar.gz

Was publish macht:

  1. Lädt das tarball unter --url herunter (mit URL- und Größenschutz) und extrahiert das manifest aus diesen Bytes.
  2. Setzt Ihre Atmosphere account-Sitzung fort und prüft publisher pinning — die aktive Sitzung muss mit dem gepinnten publisher des manifests übereinstimmen, oder es wird mit MANIFEST_PUBLISHER_MISMATCH abgelehnt.
  3. Erstellt das Paketprofil aus dem manifest bei der ersten Veröffentlichung (license, Autor, Sicherheitskontakt). Bei späteren Veröffentlichungen gewinnt das bestehende Profil.
  4. Veröffentlicht die Profil- und Versionsdatensätze in Ihrem Account.

Bei der ersten Veröffentlichung können Sie Profilfelder per Flag (--license, --security-email, …) statt über das manifest angeben; explizite Flags überschreiben manifest-Werte, was in CI praktisch ist. --no-manifest verzichtet vollständig auf das manifest.

Versionen sind unveränderlich

Eine veröffentlichte Version kann nicht überschrieben oder erneut veröffentlicht werden. Erhöhen Sie version, bevor Sie erneut veröffentlichen. Der Build liest version aus package.json (siehe die manifest-Referenz). Erhöhen Sie major für einen erweiterten trust contract, minor für neue hooks oder routes und patch für Fixes.

Publisher-Konflikt

Wenn publish mit MANIFEST_PUBLISHER_MISMATCH fehlschlägt, ist die aktive Sitzung ein anderer Atmosphere account als der gepinnte publisher des manifests. Wechseln Sie zum gepinnten Account mit emdash-plugin switch <did>, oder aktualisieren Sie publisher im manifest, wenn Sie das Plugin tatsächlich auf einen neuen Account übertragen. Siehe Einen bestehenden Account verwenden zum Verwalten von Sitzungen.

Was Sie als nächstes lesen sollten