Publicar plugins | EmDash CMS Everything

Cuando hayas creado un plugin, puedes publicarlo en el EmDash Marketplace para que otros sitios lo instalen desde el panel de administración.

Requisitos previos

Antes de publicar, asegúrate de que tu plugin:

Tenga un package.json válido con el export "." apuntando a la entrada del plugin
Use definePlugin() con un id único y una version semver válida
Declare sus capabilities (qué APIs necesita)

Formato del bundle

Los plugins publicados se distribuyen como archivos .tar.gz que contienen:

Archivo	Obligatorio	Descripción
`manifest.json`	Sí	Metadatos del plugin extraídos de `definePlugin()`
`backend.js`	No	Código de sandbox empaquetado (módulo ES autocontenido)
`admin.js`	No	Código de la UI de administración empaquetado
`README.md`	No	Documentación del plugin
`icon.png`	No	Icono del plugin (PNG 256x256)
`screenshots/`	No	Hasta 5 capturas (PNG/JPEG, máx. 1920x1080)

El manifest.json se genera automáticamente desde tu llamada a definePlugin(). Contiene el ID del plugin, la versión, las capabilities, los nombres de hooks y rutas y la configuración de admin — pero no código ejecutable.

Crear un bundle

El comando emdash plugin bundle produce un tarball desde el código fuente del plugin:

cd packages/plugins/my-plugin
emdash plugin bundle

Esto hará:

Leer tu package.json para encontrar los puntos de entrada
Compilar la entrada principal con tsdown para extraer el manifest
Empaquetar backend.js (minificado, tree-shaken, autocontenido)
Empaquetar admin.js si existe un export "./admin"
Recopilar assets (README, icono, capturas)
Validar el bundle (límites de tamaño, sin builtins de Node.js en el backend)
Escribir {id}-{version}.tar.gz en dist/

Resolución del punto de entrada

El comando bundle localiza tu código mediante los exports de package.json:

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

Export	Propósito	Se construye como
`"."`	Entrada principal — para extraer el manifest	Externals: `emdash`, `@emdash-cms/*`
`"./sandbox"`	Código de backend que corre en el sandbox	Totalmente autocontenido (sin externals)
`"./admin"`	Componentes de la UI de admin	Totalmente autocontenido

Si falta "./sandbox", el comando busca src/sandbox-entry.ts como respaldo.

Opciones

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

Flag	Por defecto	Descripción
`--dir`	Directorio actual	Directorio fuente del plugin
`--outDir`, `-o`	`dist`	Directorio de salida del tarball

Validación

El comando bundle comprueba:

Límite de tamaño — El bundle total debe ser menor de 5MB
Sin builtins de Node.js — backend.js no puede importar fs, path, child_process, etc. (el código del sandbox corre en un isolate V8, no en Node.js)
Dimensiones del icono — icon.png debería ser 256x256 (avisa si no, pero lo incluye igual)
Límites de capturas — Máx. 5 capturas, máx. 1920x1080

Publicación

El comando emdash plugin publish sube tu tarball al marketplace:

emdash plugin publish

Encontrará el .tar.gz más reciente en tu directorio dist/ y lo subirá. También puedes indicar el tarball explícitamente o compilar antes de publicar:

# Ruta explícita del tarball
emdash plugin publish --tarball dist/my-plugin-1.0.0.tar.gz

# Compilar primero y luego publicar
emdash plugin publish --build

Autenticación

La primera vez que publicas, la CLI te autentica vía GitHub:

La CLI abre el navegador en la página de autorización por dispositivo de GitHub
Introduces el código que aparece en la terminal
GitHub emite un access token
La CLI lo intercambia por un JWT del marketplace (guardado en ~/.config/emdash/auth.json)

El token dura 30 días. Tras caducar, se te pedirá volver a autenticarte en el siguiente publish.

También puedes gestionar la autenticación por separado:

# Iniciar sesión sin publicar
emdash plugin login

# Cerrar sesión (borrar token guardado)
emdash plugin logout

Registro por primera vez

Si tu plugin ID aún no existe en el marketplace, emdash plugin publish lo registra automáticamente antes de subir la primera versión.

Requisitos de versión

Cada versión publicada debe tener un semver mayor que la anterior. No puedes sobrescribir ni volver a publicar una versión existente.

Auditoría de seguridad

Cada versión publicada pasa por una auditoría de seguridad automatizada. El marketplace escanea tu backend.js y admin.js en busca de:

Patrones de exfiltración de datos
Recolección de credenciales vía settings
Código ofuscado
Abuso de recursos (crypto mining, etc.)
Actividad de red sospechosa

La auditoría produce un veredicto pass, warn o fail, que se muestra en la ficha del plugin en el marketplace. Según el nivel de enforcement del marketplace, un veredicto fail puede bloquear por completo la publicación.

Opciones

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

Flag	Por defecto	Descripción
`--tarball`	Último `.tar.gz` en `dist/`	Ruta explícita del tarball
`--build`	`false`	Ejecutar `emdash plugin bundle` antes de publicar
`--dir`	Directorio actual	Directorio del plugin (con `--build`)
`--registry`	`https://marketplace.emdashcms.com`	URL del marketplace

Flujo completo

Ciclo típico de publicación:

# 1. Haz tus cambios
# 2. Sube la versión en definePlugin() y package.json
# 3. Empaqueta y publica en un paso
emdash plugin publish --build

O si prefieres inspeccionar el bundle primero:

# Crear el tarball
emdash plugin bundle

# Revisar la salida
tar tzf dist/my-plugin-1.1.0.tar.gz

# Publicar
emdash plugin publish