Pubblicare i plugin | EmDash CMS Everything

Dopo aver sviluppato un plugin, puoi pubblicarlo sull’EmDash Marketplace così che altri siti lo installino dalla dashboard di amministrazione.

Prerequisiti

Prima di pubblicare, assicurati che il plugin:

Abbia un package.json valido con l’export "." che punta all’entry del plugin
Usi definePlugin() con un id univoco e una version semver valida
Dichiari le sue capabilities (quali API deve usare)

Formato del bundle

I plugin pubblicati sono distribuiti come archivi .tar.gz che contengono:

File	Obbligatorio	Descrizione
`manifest.json`	Sì	Metadati del plugin estratti da `definePlugin()`
`backend.js`	No	Codice sandbox in bundle (modulo ES autonomo)
`admin.js`	No	Codice UI admin in bundle
`README.md`	No	Documentazione del plugin
`icon.png`	No	Icona del plugin (PNG 256x256)
`screenshots/`	No	Fino a 5 screenshot (PNG/JPEG, max 1920x1080)

Il manifest.json viene generato automaticamente dalla chiamata definePlugin(). Contiene ID del plugin, versione, capabilities, nomi degli hook e delle route e la configurazione admin — ma nessun codice eseguibile.

Creare un bundle

Il comando emdash plugin bundle produce un tarball dal sorgente del plugin:

cd packages/plugins/my-plugin
emdash plugin bundle

Esegue:

Legge il package.json per trovare gli entrypoint
Compila l’entry principale con tsdown per estrarre il manifest
Crea il bundle di backend.js (minificato, tree-shaken, autonomo)
Crea il bundle di admin.js se esiste l’export "./admin"
Raccoglie gli asset (README, icona, screenshot)
Valida il bundle (limiti di dimensione, nessun builtin Node.js nel backend)
Scrive {id}-{version}.tar.gz in dist/

Risoluzione degli entrypoint

Il comando bundle trova il codice tramite gli export di package.json:

{
  "exports": {
    ".": { "import": "./dist/index.mjs" },
    "./sandbox": { "import": "./dist/sandbox-entry.mjs" },
    "./admin": { "import": "./dist/admin.mjs" }
  }
}

Export	Scopo	Costruito come
`"."`	Entry principale — per estrarre il manifest	Externals: `emdash`, `@emdash-cms/*`
`"./sandbox"`	Codice backend che gira nella sandbox	Completamente autonomo (nessun external)
`"./admin"`	Componenti UI admin	Completamente autonomo

Se manca "./sandbox", il comando cerca src/sandbox-entry.ts come fallback.

Opzioni

emdash plugin bundle [--dir <path>] [--outDir <path>]

Flag	Predefinito	Descrizione
`--dir`	Directory corrente	Directory sorgente del plugin
`--outDir`, `-o`	`dist`	Directory di output del tarball

Validazione

Il comando bundle controlla:

Limite di dimensione — Il bundle totale deve essere sotto 5MB
Nessun builtin Node.js — backend.js non può importare fs, path, child_process, ecc. (il codice sandbox gira in un isolate V8, non in Node.js)
Dimensioni icona — icon.png dovrebbe essere 256x256 (avvisa se errato, ma la include comunque)
Limiti screenshot — Max 5 screenshot, max 1920x1080

Pubblicazione

Il comando emdash plugin publish carica il tarball sul marketplace:

emdash plugin publish

Troverà il .tar.gz più recente in dist/ e lo caricherà. Puoi anche specificare il tarball esplicitamente o compilare prima di pubblicare:

# Percorso esplicito del tarball
emdash plugin publish --tarball dist/my-plugin-1.0.0.tar.gz

# Compila prima, poi pubblica
emdash plugin publish --build

Autenticazione

La prima volta che pubblichi, la CLI ti autentica tramite GitHub:

La CLI apre il browser sulla pagina di autorizzazione dispositivo di GitHub
Inserisci il codice mostrato nel terminale
GitHub emette un access token
La CLI lo scambia con un JWT del marketplace (salvato in ~/.config/emdash/auth.json)

Il token dura 30 giorni. Dopo la scadenza, ti verrà chiesta una nuova autenticazione al prossimo publish.

Puoi gestire l’autenticazione separatamente:

# Accedi senza pubblicare
emdash plugin login

# Esci (cancella il token salvato)
emdash plugin logout

Registrazione iniziale

Se l’ID del plugin non esiste ancora sul marketplace, emdash plugin publish lo registra automaticamente prima di caricare la prima versione.

Requisiti di versione

Ogni versione pubblicata deve avere un semver superiore alla precedente. Non puoi sovrascrivere o ripubblicare una versione esistente.

Security audit

Ogni versione pubblicata passa un security audit automatizzato. Il marketplace analizza backend.js e admin.js per:

Pattern di exfiltration dei dati
Raccolta di credenziali tramite settings
Codice offuscato
Abuso di risorse (crypto mining, ecc.)
Attività di rete sospette

L’audit produce un verdetto pass, warn o fail, mostrato nella scheda del plugin sul marketplace. A seconda del livello di enforcement del marketplace, un verdetto fail può bloccare completamente la pubblicazione.

Opzioni

emdash plugin publish [--tarball <path>] [--build] [--dir <path>] [--registry <url>]

Flag	Predefinito	Descrizione
`--tarball`	Ultimo `.tar.gz` in `dist/`	Percorso esplicito del tarball
`--build`	`false`	Eseguire `emdash plugin bundle` prima della pubblicazione
`--dir`	Directory corrente	Directory del plugin (con `--build`)
`--registry`	`https://marketplace.emdashcms.com`	URL del marketplace

Workflow completo

Ciclo di pubblicazione tipico:

# 1. Apporta le modifiche
# 2. Incrementa la versione in definePlugin() e package.json
# 3. Bundle e publish in un solo passo
emdash plugin publish --build

Oppure, se preferisci ispezionare prima il bundle:

# Crea il tarball
emdash plugin bundle

# Controlla l’output
tar tzf dist/my-plugin-1.1.0.tar.gz

# Pubblica
emdash plugin publish