Installare i plugin

Gli amministratori possono installare plugin sandboxed dal registro dei plugin oppure registrare pacchetti npm in astro.config.mjs. I plugin basati sulla configurazione possono essere eseguiti nella sandbox o nel processo del sito.

Prepararsi alle installazioni dall’admin

Le installazioni dal registro richiedono:

• Un account amministratore con il permesso plugins:manage.
• Uno storage configurato per i bundle dei plugin scaricati.
• Un runner di sandbox disponibile.

Su Cloudflare Workers, usa sandbox() da @emdash-cms/cloudflare:

import { sandbox } from "@emdash-cms/cloudflare";
import { defineConfig } from "astro/config";
import emdash from "emdash/astro";

export default defineConfig({
	integrations: [
		emdash({
			sandboxRunner: sandbox(),
		}),
	],
});

Il runner Cloudflare usa Worker Loader per creare un Worker separato per ogni plugin. Richiede il piano Workers Paid e un binding worker_loaders chiamato LOADER. I plugin sandboxed accedono alle API di contenuti, media, storage, rete ed email tramite PluginBridge, quindi l’entry point Worker del sito deve esportare quella classe.

I template *-cloudflare esportano PluginBridge ma lasciano commentato il binding Worker Loader, così i nuovi progetti possono essere distribuiti sul piano gratuito di Workers. Abilita i plugin sandboxed durante lo scaffolding oppure segui la configurazione della sandbox Cloudflare per aggiungere il binding in seguito. L’helper sandbox() legge la configurazione Wrangler effettiva al momento della build. Senza LOADER, la navigazione del registro resta disponibile, ma i plugin sandboxed gestiti dalla configurazione non vengono caricati e le richieste di installazione o aggiornamento restituiscono SANDBOX_NOT_AVAILABLE.

Su Node.js, installa il runner e la sua peer dependency workerd:

npm install @emdash-cms/sandbox-workerd workerd

Il processo workerd esegue il codice del plugin separatamente dal server Node.js. Seleziona il runner nell’integrazione EmDash:

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";

export default defineConfig({
	integrations: [
		emdash({
			sandboxRunner: "@emdash-cms/sandbox-workerd/sandbox",
		}),
	],
});

Consulta Configurare la sandbox dei plugin per la configurazione di sviluppo, i requisiti di runtime, i limiti delle risorse e gli errori di runner non disponibile su entrambe le piattaforme.

Installare dal registro

EmDash verifica i record firmati correnti del publisher e controlla il bundle scaricato prima di caricarlo tramite il runner di sandbox. Il plugin compare in Plugins, dove puoi disabilitarlo o configurarlo. Consulta Il registro dei plugin per il modello completo di verifica e fiducia.

Esaminare i permessi

La finestra di consenso mostra tutti i permessi dichiarati dal plugin. I permessi comuni includono:

La finestra identifica anche le route del plugin esposte come strumenti del Model Context Protocol (MCP) quando un plugin le dichiara. Consulta Capability e sicurezza per il modello completo dei permessi.

Aggiornare un plugin

Gli aggiornamenti del registro richiedono un’ulteriore conferma quando aggiungono permessi o strumenti MCP, oppure quando una route passa da autenticata a pubblica. EmDash lascia installata la versione corrente finché non approvi la modifica.

Gli aggiornamenti espliciti procedono solo in avanti. Gli aggiornamenti che seguono l’ultima release del registro possono essere annullati se il publisher ritira la release più recente. Per tornare a una release precedente in qualsiasi altro momento, disinstalla il plugin e installa quella versione dalla sua pagina del registro. La disinstallazione conserva i dati memorizzati del plugin, a meno che tu non scelga di eliminarli.

Disinstallare un plugin

EmDash rimuove il bundle installato e smette di caricare il plugin. I dati di storage del plugin restano per impostazione predefinita.

Installare da npm

I plugin nativi e i plugin sandboxed gestiti dalla configurazione si installano come dipendenze npm. Segui le istruzioni del pacchetto per scegliere plugins: [] o sandboxed: [].

L’esempio seguente registra il plugin nativo Field Kit:

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { fieldKitPlugin } from "@emdash-cms/plugin-field-kit";

export default defineConfig({
	integrations: [
		emdash({
			plugins: [fieldKitPlugin()],
		}),
	],
});

I plugin gestiti dalla configurazione cambiano quando aggiorni la dipendenza npm ed esegui il deploy del sito. Non possono essere installati né rimossi dal pannello di amministrazione.

Scegliere un metodo di installazione

Usa un plugin nativo quando ha bisogno di componenti di amministrazione React, renderer di Portable Text, frammenti di pagina o accesso diretto al processo del sito. Usa un plugin sandboxed quando può funzionare tramite le API dei plugin dichiarate.