I plugin EmDash vengono forniti in uno di due formati: sandboxed o native. La scelta influisce su come viene installato il plugin, quale applicazione ottiene a runtime e quali funzionalità sono disponibili.
Di default, usate sandboxed. I plugin sandboxed possono essere pubblicati sul marketplace e installati dall’interfaccia di amministrazione con un solo clic. I plugin nativi richiedono una modifica del codice, un npm install e un ridistribuzione su ogni sito che li desidera. Sandboxed è ciò che gli utenti finali vogliono.
Scegliete native solo quando avete bisogno di una funzionalità che il sandbox non può fornire.
A colpo d’occhio
| Sandboxed | Native | |
|---|---|---|
Campo format nel descrittore | "standard" | "native" |
| Metodo di installazione | Un clic dal marketplace di amministrazione | npm install + modificare astro.config |
| Esegue in | Un runtime isolato fornito da un sandbox runner | Lo stesso processo del vostro sito Astro |
| Capacità | Applicate dal ponte del sandbox | Applicate in-process dallo stesso ponte |
| Limiti di risorse | Applicati dal runner — tipicamente CPU, subrequests, tempo di esecuzione, memoria | Nessuno |
| Accesso alla rete | Solo ctx.http, limitato a allowedHosts | Solo ctx.http, limitato a allowedHosts |
fetch() / process.env diretto | Bloccato dal runner | Possibile (il codice del plugin condivide il runtime) |
| Distribuzione | Bundle .tar.gz sul marketplace | Pacchetto npm |
| Interfaccia di amministrazione | Route Block Kit (descritte in JSON) | Componenti React o Block Kit |
| Interfaccia delle impostazioni | Pagina Block Kit + letture KV | admin.settingsSchema (modulo automatico) o Block Kit |
| Componenti di rendering Portable Text | Non disponibile | componentsEntry fornisce componenti Astro |
| Contributi ai metadati della pagina | Hook page:metadata — tag meta/property, rels <link> consentiti, JSON-LD | Hook page:metadata (stessa superficie) |
| Iniezione di frammenti di pagina | Non disponibile — solo meta/JSON-LD via page:metadata | Hook page:fragments — script inline, script esterni, HTML grezzo |
| Opzioni del costruttore | Nessuna — leggere le impostazioni da KV a runtime | options nel descrittore |
Cosa si rinuncia scegliendo native
I plugin nativi sembrano una versione più potente della stessa cosa, e lo sono — ma il costo è alto:
- Nessun marketplace. Ogni sito deve installare il vostro pacchetto npm, modificare
astro.config.mjse ridistribuire. - Nessun isolamento. Un bug nel vostro plugin può bloccare il processo host o esaurire il suo budget CPU. Un rifiuto non gestito in un hook può abbattere la richiesta circostante con esso.
- Onere di fiducia sull’utente. I plugin nativi hanno lo stesso accesso del sito host. Gli utenti finali non possono verificarli solo attraverso dichiarazioni di capacità.
Se il vostro plugin può svolgere il suo lavoro nel sandbox, dovrebbe farlo.
Quando scegliere native
Ci sono tre motivi per scegliere native, e riguardano tutti funzionalità che necessitano di integrazione al momento della build con il sito host:
-
Pagine di amministrazione o widget React personalizzati. I plugin sandboxed descrivono la loro interfaccia di amministrazione con Block Kit — uno schema JSON che l’amministratore renderizza per conto del plugin. Se avete bisogno di React completo (hook personalizzati, componenti di terze parti, stato complesso), avete bisogno di native.
-
Componenti Astro per il rendering di blocchi Portable Text sul sito pubblico. Un plugin può dichiarare un tipo di blocco personalizzato con
format: "standard", ma i componenti Astro che lo renderizzano sul sito pubblico devono essere caricati al momento della build da npm. Solo i plugin nativi possono fornire uncomponentsEntry. -
Iniettare HTML grezzo, script o fogli di stile in pagine pubbliche. L’hook
page:fragmentsspedisce codice proprietario ai browser dei visitatori — al di fuori di qualsiasi limite del sandbox. È limitato ai plugin nativi. I plugin sandboxed possono comunque contribuire alle pagine pubbliche tramite l’hookpage:metadata, che copre molti casi d’uso reali:- Tag
meta(name+content) — descrizioni SEO, direttive robots, Twitter Cards - Tag
property— OpenGraph e altri metadati basati su proprietà - Tag
linkcon una lista consentita di rel bloccata per sicurezza (canonical,alternate,author,license,nlweb,site.standard.document) —stylesheet,prefetche rels simili di caricamento risorse non sono deliberatamente consentiti - Grafi JSON-LD
Se la vostra esigenza di “iniezione di pagina” riguarda dati strutturati o metadati SEO, rimanete in sandboxed e usate
page:metadata. Se dovete effettivamente spedire JavaScript o HTML al browser del visitatore, quello è il caso per scegliere native. - Tag
Se non siete sicuri, scegliete sandboxed. Potete sempre migrare a native in seguito — ma il contrario è più difficile, perché le funzionalità esclusive di native non hanno equivalenti sandbox.
Sandbox runner e supporto della piattaforma
Il sandbox stesso è pluggable. EmDash espone un’opzione di configurazione sandboxRunner e il runner decide come il codice del plugin viene isolato — non c’è nulla di specifico di Cloudflare nel formato del plugin stesso.
Il runner che la maggior parte dei siti usa oggi è sandbox() da @emdash-cms/cloudflare, che utilizza il Dynamic Worker Loader di Cloudflare Workers. Worker Loader memorizza nella cache l’isolato V8 per ID plugin, quindi il costo di avvio a freddo dell’isolato viene pagato solo una volta; il runner costruisce uno stub worker fresco e binding del ponte a ogni invocazione, poiché gli stub e i binding sono legati al contesto I/O della richiesta chiamante. I runner per altre piattaforme (Node.js via workerd e potenzialmente Deno) sono in sviluppo.
Se non è configurato alcun runner, o se il runner configurato segnala di non essere disponibile sulla piattaforma corrente, i plugin elencati sotto sandboxed: [] vengono saltati all’avvio con un log di livello debug.
Se desiderate che un plugin in formato standard venga eseguito su una piattaforma senza un sandbox runner, spostatelo da sandboxed: [] nell’array plugins: [] — verrà eseguito in-process. Le dichiarazioni di capacità sono comunque rispettate (la stessa factory PluginContext limita ctx.content, ctx.http e simili), ma non c’è limite di isolamento, nessun limite di risorse, e un plugin difettoso o malevolo può chiamare fetch() direttamente, leggere variabili di ambiente o bloccare il loop degli eventi. Senza un sandbox runner attivo, trattate ogni plugin come un plugin nativo a scopi di fiducia.