Publicar plugins | EmDash CMS Everything

Depois de criar um plugin, pode publicá-lo no EmDash Marketplace para que outros sites o instalem a partir do painel de administração.

Pré-requisitos

Antes de publicar, certifique-se de que o plugin:

Tem um package.json válido com o export "." a apontar para a entrada do plugin
Usa definePlugin() com um id único e uma version semver válida
Declara as suas capabilities (que APIs precisa)

Formato do bundle

Os plugins publicados são distribuídos como ficheiros .tar.gz contendo:

Ficheiro	Obrigatório	Descrição
`manifest.json`	Sim	Metadados do plugin extraídos de `definePlugin()`
`backend.js`	Não	Código sandbox empacotado (módulo ES autónomo)
`admin.js`	Não	Código da UI de admin empacotado
`README.md`	Não	Documentação do plugin
`icon.png`	Não	Ícone do plugin (PNG 256x256)
`screenshots/`	Não	Até 5 capturas (PNG/JPEG, máx. 1920x1080)

O manifest.json é gerado automaticamente a partir da chamada definePlugin(). Contém o ID do plugin, versão, capabilities, nomes de hooks e rotas e configuração de admin — mas sem código executável.

Criar um bundle

O comando emdash plugin bundle produz um tarball a partir do código-fonte do plugin:

cd packages/plugins/my-plugin
emdash plugin bundle

Isto irá:

Ler o package.json para encontrar os pontos de entrada
Compilar a entrada principal com tsdown para extrair o manifest
Empacotar backend.js (minificado, tree-shaken, autónomo)
Empacotar admin.js se existir export "./admin"
Recolher assets (README, ícone, capturas)
Validar o bundle (limites de tamanho, sem builtins Node.js no backend)
Escrever {id}-{version}.tar.gz para dist/

Resolução do ponto de entrada

O comando bundle encontra o código através dos exports do package.json:

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

Export	Finalidade	Construído como
`"."`	Entrada principal — para extrair o manifest	Externals: `emdash`, `@emdash-cms/*`
`"./sandbox"`	Código de backend na sandbox	Totalmente autónomo (sem externals)
`"./admin"`	Componentes da UI admin	Totalmente autónomo

Se "./sandbox" faltar, o comando procura src/sandbox-entry.ts como alternativa.

Opções

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

Flag	Predefinição	Descrição
`--dir`	Diretório atual	Diretório fonte do plugin
`--outDir`, `-o`	`dist`	Diretório de saída do tarball

Validação

O comando bundle verifica:

Limite de tamanho — O bundle total deve ser inferior a 5MB
Sem builtins Node.js — backend.js não pode importar fs, path, child_process, etc. (código sandbox corre num isolate V8, não em Node.js)
Dimensões do ícone — icon.png deve ser 256x256 (avisa se incorreto, mas inclui na mesma)
Limites de capturas — Máx. 5 capturas, máx. 1920x1080

Publicação

O comando emdash plugin publish envia o tarball para o marketplace:

emdash plugin publish

Encontrará o .tar.gz mais recente em dist/ e fará o upload. Também pode especificar o tarball explicitamente ou compilar antes de publicar:

# Caminho explícito do tarball
emdash plugin publish --tarball dist/my-plugin-1.0.0.tar.gz

# Compilar primeiro, depois publicar
emdash plugin publish --build

Autenticação

Na primeira publicação, a CLI autentica-o via GitHub:

A CLI abre o browser na página de autorização por dispositivo do GitHub
Introduz o código mostrado no terminal
O GitHub emite um access token
A CLI troca-o por um JWT do marketplace (guardado em ~/.config/emdash/auth.json)

O token dura 30 dias. Após expirar, será pedida nova autenticação no próximo publish.

Também pode gerir a autenticação separadamente:

# Iniciar sessão sem publicar
emdash plugin login

# Terminar sessão (limpar token guardado)
emdash plugin logout

Registo inicial

Se o ID do plugin ainda não existir no marketplace, emdash plugin publish regista-o automaticamente antes de carregar a primeira versão.

Requisitos de versão

Cada versão publicada deve ter semver superior à anterior. Não pode sobrescrever nem voltar a publicar uma versão existente.

Auditoria de segurança

Cada versão publicada passa por uma auditoria de segurança automatizada. O marketplace analisa backend.js e admin.js à procura de:

Padrões de exfiltração de dados
Recolha de credenciais via settings
Código ofuscado
Abuso de recursos (crypto mining, etc.)
Atividade de rede suspeita

A auditoria produz um veredicto pass, warn ou fail, mostrado na listagem do plugin no marketplace. Consoante o nível de enforcement do marketplace, um fail pode bloquear totalmente a publicação.

Opções

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

Flag	Predefinição	Descrição
`--tarball`	Último `.tar.gz` em `dist/`	Caminho explícito do tarball
`--build`	`false`	Executar `emdash plugin bundle` antes de publicar
`--dir`	Diretório atual	Diretório do plugin (com `--build`)
`--registry`	`https://marketplace.emdashcms.com`	URL do marketplace

Fluxo completo

Ciclo típico de publicação:

# 1. Faça as alterações
# 2. Suba a versão em definePlugin() e package.json
# 3. Empacotar e publicar num passo
emdash plugin publish --build

Ou, se preferir inspecionar o bundle primeiro:

# Criar o tarball
emdash plugin bundle

# Verificar a saída
tar tzf dist/my-plugin-1.1.0.tar.gz

# Publicar
emdash plugin publish