EmDash-Plugins verwenden eines von zwei Formaten: Sandbox oder nativ. Wählen Sie das Format vor dem Schreiben des Plugins, da sich die Erstellungsform, der Installationspfad und die Vertrauensgrenze unterscheiden.
Wählen Sie ein Sandbox-Plugin, es sei denn, das Plugin benötigt eine rein native Integration. Sandbox-Plugins können im Registry veröffentlicht und über die Admin-UI installiert werden. Ein natives Plugin ist ein npm-Paket, das ein Site-Betreiber im Projekt installiert und zu astro.config.mjs hinzufügt, bevor er neu bereitstellt.
Auf einen Blick
| Sandbox | Nativ | |
|---|---|---|
| Erstellungsform | emdash-plugin.jsonc + src/plugin.ts | definePlugin()-Deskriptor |
| Installationsmethode | Ein Klick aus dem Admin-Registry | npm install + astro.config bearbeiten |
| Läuft in | Einer isolierten Runtime, die ein Sandbox-Runner bereitstellt | Demselben Prozess wie Ihre Astro-Site |
Capability-gesteuerte ctx-APIs | Durch die Sandbox-Bridge durchgesetzt | Durch PluginContext gesteuert, aber keine Sicherheitsgrenze |
| Ressourcengrenzen | Runner-Grenzen für CPU, Subrequests und Wanduhrzeit; Plattform-Speicherobergrenze | Keine Plugin-spezifischen Grenzen |
| Netzwerkzugriff | ctx.http, auf deklarierten Zugriff beschränkt | ctx.http folgt Deklarationen; nativer Code kann auch fetch() aufrufen |
Direkter fetch() / process.env | Vom Runner blockiert | Möglich (Plugin-Code teilt die Runtime) |
| Verteilung | Signiertes Release im Plugin-Registry | npm-Paket |
| Admin-UI | Block Kit (JSON-beschriebene) Routen | React-Komponenten oder Block Kit |
| Einstellungs-UI | Block Kit-Seite + ctx.settings | admin.settingsSchema (Auto-Formular) oder Block Kit |
| Portable Text Rendering-Komponenten | Nicht verfügbar | componentsEntry stellt Astro-Komponenten bereit |
| Page-Metadata-Beiträge | page:metadata-Hook — Meta/Property-Tags, zugelassene <link> rels, JSON-LD | page:metadata-Hook (gleiche Oberfläche) |
| Page-Fragment-Injektion | Nicht verfügbar — nur Meta/JSON-LD über page:metadata | page:fragments-Hook — Inline-Skripte, externe Skripte, rohes HTML |
| Konstruktoroptionen | Keine — Einstellungen zur Laufzeit aus KV lesen | options auf dem Deskriptor |
Kosten eines nativen Plugins
Native Plugins haben ein anderes Installations- und Vertrauensmodell:
- Installation auf Projektebene. Jede Site muss Ihr npm-Paket installieren,
astro.config.mjsbearbeiten und neu bereitstellen. - Keine Isolierung. Ein Fehler in Ihrem Plugin kann den Host-Prozess zum Absturz bringen oder sein CPU-Budget aufbrauchen. Eine unbehandelte Ablehnung in einem Hook kann die umgebende Anfrage mit sich reißen.
- Vertrauenslast beim Benutzer. Native Plugins haben denselben Zugriff wie die Host-Site. Capability-Deklarationen allein können nicht alles zeigen, was ihr Code tun kann.
Wenn Ihr Plugin seine Aufgabe in der Sandbox erledigen kann, sollte es das tun.
Wann nativ werden
Wählen Sie nativ für Funktionen, die Build-Zeit-Integration mit der Host-Site benötigen:
-
Benutzerdefinierte React-Admin-Seiten oder -Widgets. Sandbox-Plugins beschreiben ihre Admin-UI mit Block Kit — einem JSON-Schema, das der Admin im Namen des Plugins rendert. Wenn Sie vollständiges React benötigen (benutzerdefinierte Hooks, Drittanbieter-Komponenten, komplexer State), brauchen Sie nativ.
-
Benutzerdefinierte Portable Text-Blocktypen. Ihre Bearbeitungskonfiguration und Astro-Rendering-Komponenten werden aus dem installierten npm-Paket geladen. Nur native Plugins können diese Build-Zeit-Oberfläche bereitstellen.
-
Rohes HTML, Skripte oder Stylesheets in öffentliche Seiten injizieren. Der
page:fragments-Hook liefert First-Party-Code an die Browser der Besucher — außerhalb jeder Sandbox-Grenze. Er ist auf native Plugins beschränkt. Sandbox-Plugins können dennoch über denpage:metadata-Hook zu öffentlichen Seiten beitragen, der viele echte Anwendungsfälle abdeckt:meta-Tags (name+content) — SEO-Beschreibungen, Robots-Direktiven, Twitter-Kartenproperty-Tags — OpenGraph und andere Property-basierte Metalink-Tags mit einer sicherheitsgesperrten rel-Allowlist (canonical,alternate,author,license,nlweb,site.standard.document) —stylesheet,prefetchund ähnliche ressourcenladende rels sind absichtlich nicht erlaubt- JSON-LD-Graphen
Wenn Ihr “Seiten-Injektions”-Bedarf strukturierte Daten oder SEO-Metadaten ist, bleiben Sie bei Sandbox und verwenden Sie
page:metadata. Wenn Sie tatsächlich JavaScript oder HTML in den Browser des Besuchers liefern müssen, ist das der Fall für nativ.
Wenn keine dieser Funktionen zutrifft, verwenden Sie das Sandbox-Format.
Sandbox-Runner und Plattformunterstützung
Die Sandbox selbst ist pluggable. EmDash stellt eine sandboxRunner-Konfigurationsoption bereit, und der Runner entscheidet, wie Plugin-Code isoliert wird — es gibt nichts Cloudflare-spezifisches im Plugin-Format selbst.
Zwei Runner werden mit EmDash ausgeliefert: sandbox() aus @emdash-cms/cloudflare, das jedes Plugin als Dynamic Worker über Cloudflares Worker Loader ausführt, und @emdash-cms/sandbox-workerd/sandbox, das Plugins in einem workerd-Kindprozess auf Node.js ausführt. Plugin Sandbox behandelt die Einrichtung jedes Runners, die von ihm durchgesetzten Ressourcengrenzen und die Unterschiede zwischen den beiden.
Wenn kein Runner konfiguriert ist, werden Plugins, die unter sandboxed: [] aufgeführt sind, nicht geladen. Wenn der konfigurierte Runner auf der aktuellen Plattform nicht verfügbar ist, werden sie auch nicht geladen, und EmDash protokolliert beim Start eine Warnung.
Wenn Sie möchten, dass ein Sandbox-Plugin auf einer Plattform ohne Sandbox-Runner läuft, verschieben Sie es von sandboxed: [] in das plugins: []-Array — es wird in-process ausgeführt. Capability-Deklarationen werden weiterhin berücksichtigt (dieselbe PluginContext-Factory steuert ctx.content, ctx.http und Freunde), aber es gibt keine Isolierungsgrenze, keine Ressourcengrenzen, und ein fehlerhaftes oder bösartiges Plugin kann fetch() direkt aufrufen, Umgebungsvariablen lesen oder die Event-Loop blockieren. Ohne einen aktiven Sandbox-Runner behandeln Sie jedes Plugin für Vertrauenszwecke als natives Plugin.