Instalar plugins

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

Preparar-se para instalações pelo admin

As instalações pelo registro exigem:

• Uma conta de administrador com a permissão plugins:manage.
• Armazenamento configurado para os pacotes de plugins baixados.
• Um runner de sandbox 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 da Cloudflare usa o Worker Loader para criar um Worker separado para cada plugin. Ele exige o plano Workers Paid e um binding worker_loaders chamado LOADER. Os plugins em sandbox acessam as APIs de conteúdo, mídia, armazenamento, rede e e-mail por meio do PluginBridge, então o ponto de entrada do Worker do site precisa exportar essa classe.

Os templates *-cloudflare exportam PluginBridge, mas deixam o binding do Worker Loader comentado, para que novos projetos possam ser implantados no plano gratuito do Workers. Habilite os plugins em sandbox durante a geração do projeto ou siga a configuração do sandbox da Cloudflare para adicionar o binding depois. O helper sandbox() lê a configuração efetiva do Wrangler em tempo de build. Sem LOADER, a navegação pelo registro continua disponível, mas os plugins em sandbox gerenciados pela configuração não são carregados, e as requisiçõ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 do EmDash:

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

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

Consulte Configurar o sandbox de plugins para a configuração de desenvolvimento, os requisitos de runtime, os limites de recursos e os erros de runner indisponível nas duas plataformas.

Instalar a partir do registro

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

Revisar permissões

O diálogo de consentimento mostra todas as permissões declaradas pelo plugin. As permissões comuns incluem:

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

Atualizar um plugin

As atualizações do registro exigem outra confirmação quando adicionam permissões ou ferramentas MCP, ou quando uma rota passa de autenticada para pública. O EmDash mantém a versão instalada até que você aprove a mudança.

As atualizações explícitas só avançam. As atualizações que acompanham a versão mais recente do registro podem ser revertidas se o publicador retirar a versão mais nova. Para voltar a uma versão mais antiga em qualquer outro momento, desinstale o plugin e instale essa versão a partir da página dele no registro. Desinstalar mantém os dados armazenados do plugin, a menos que você escolha excluí-los.

Desinstalar um plugin

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

Instalar a partir do npm

Os plugins nativos e os plugins em sandbox gerenciados pela configuração são instalados 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()],
		}),
	],
});

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

Escolher um método de instalação

Use um plugin nativo quando ele precisar de componentes de administração em React, renderizadores de Portable Text, fragmentos de página ou acesso direto ao processo do site. Use um plugin em sandbox quando ele puder funcionar por meio das APIs de plugin declaradas.