Instalar plugins

Administradores podem instalar plugins sandboxed a partir do registro de plugins ou registrar pacotes npm em astro.config.mjs. Plugins baseados em configuração podem ser executados no sandbox ou no processo do site.

Preparar-se para instalações pelo admin

Instalações a partir do registro exigem:

• Uma conta de administrador com a permissão plugins:manage.
• Armazenamento configurado para bundles de plugins baixados.
• Um sandbox runner disponível.

No Cloudflare Workers, use sandbox() de @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(),
		}),
	],
});

O runner do Cloudflare usa Worker Loader para criar um Worker separado para cada plugin. Exige o plano Workers Paid e um binding worker_loaders chamado LOADER. Plugins sandboxed alcançam APIs de conteúdo, mídia, armazenamento, rede e e-mail por meio de PluginBridge, portanto o ponto de entrada Worker do site deve exportar essa classe.

Os modelos *-cloudflare exportam PluginBridge mas deixam o binding Worker Loader comentado, de modo que novos projetos podem ser implantados no plano gratuito do Workers. Habilite plugins sandboxed durante o scaffolding ou siga a configuração do sandbox do Cloudflare para adicionar o binding depois. O helper sandbox() lê a configuração efetiva do Wrangler no momento do build. Sem LOADER, a navegação no registro permanece disponível, mas plugins sandboxed gerenciados por configuração não carregam e solicitações de instalação ou atualização retornam SANDBOX_NOT_AVAILABLE.

No Node.js, instale o runner e sua dependência peer workerd:

npm install @emdash-cms/sandbox-workerd workerd

O processo workerd executa o código do plugin separadamente do servidor Node.js. Selecione o runner na integração EmDash:

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

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

Veja Sandbox de plugins para configuração de desenvolvimento, requisitos de runtime, limites de recursos e erros de runner indisponível em ambas as plataformas.

Instalar a partir do registro

O EmDash verifica os registros assinados atuais do publisher e verifica o bundle baixado antes de carregá-lo pelo sandbox runner. O plugin aparece em Plugins, onde você pode desabilitá-lo ou configurá-lo. Veja O registro de plugins para o modelo completo de verificação e confiança.

Revisar permissões

O diálogo de consentimento mostra cada permissão declarada pelo plugin. Permissões comuns incluem:

O diálogo também identifica rotas de plugin expostas como ferramentas Model Context Protocol (MCP) quando um plugin as declara. Veja Capabilities e segurança para o modelo completo de permissões.

Atualizar um plugin

Atualizações do registro exigem outra confirmação quando adicionam permissões ou ferramentas MCP, ou quando uma rota muda de autenticada para pública. O EmDash deixa a versão instalada no lugar até você aprovar a alteração.

Desinstalar um plugin

O EmDash remove o bundle instalado e para de carregar o plugin. Os dados de armazenamento do plugin permanecem por padrão.

Instalar a partir do npm

Plugins nativos e plugins sandboxed gerenciados por configuração instalam-se como dependências npm. Siga as instruções do pacote para escolher plugins: [] ou sandboxed: [].

O exemplo a seguir registra o 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()],
		}),
	],
});

Plugins gerenciados por configuração mudam quando você atualiza a dependência npm e implanta o site. Eles não podem ser instalados ou removidos pelo painel de administração.

Escolher um método de instalação

Use um plugin nativo quando precisar de componentes de admin React, renderizadores Portable Text, fragmentos de página ou acesso direto ao processo do site. Use um plugin sandboxed quando puder trabalhar pelas APIs de plugin declaradas.