Manifesto do plugin
Um plugin se descreve inteiro por um objeto: o PluginManifest. Ele declara o que o plugin é — navegação, rotas, widgets, dados, permissões — e o runtime faz o resto. Plugins declaram; o core resolve. Esta página é o tour pelos campos; a referência exaustiva está em referência do manifesto do plugin.
O núcleo obrigatório
Quatro campos identificam qualquer plugin, mais os dois seams que dão a ele um lugar na UI:
{
id: 'fidelidade',
name: 'Fidelidade',
icon: 'Puzzle',
version: '0.1.0',
navigation: [
{ section: 'main', position: 50, label: 'Fidelidade', route: '/fidelidade', icon: 'Puzzle' },
],
routes: [{ path: '/fidelidade', component: Page }],
}
id— identificador único do plugin.name/icon/version— rótulo, ícone e versão.navigation— os itens de menu (veja Rotas e navegação).routes— o mapeamentopath → componente.
Um componente sempre pode ser dado direto (component) ou por id de registry (componentId) — exatamente um dos dois.
Os seams de extensão
Além do núcleo, o manifesto tem uma família de campos opcionais — cada um é um "seam" pelo qual o plugin estende a plataforma sem tocar em nenhum outro plugin:
| Seam | O que declara |
|---|---|
settings | Abas na tela de configurações do plugin. |
widgets | Componentes injetados em zonas nomeadas do shell (WidgetZone). |
dashboardWidgets | KPIs, gráficos e tabelas que o plugin contribui ao dashboard. |
events | Eventos que o plugin emite no bus (agenda.booking.confirmed, …). |
aiTools | Ferramentas que um agente de IA pode chamar (modo read ou persist). |
capabilities | As capacidades declaradas do plugin (para introspecção). |
entities | Entidades de dados que o plugin registra para CRUD. |
permissions / declaredFeatures | Features e ações para o controle de acesso. |
connectors | Conectores para provedores externos (o plugin como addon de outro). |
migrations | O SQL das tabelas que o plugin possui (convenção plg_), cada uma com tenant_id + RLS. |
diagnostics | Pré-requisitos de backend que o fayz doctor verifica (RPCs, views, tabelas, env). |
onboarding | Um fluxo de primeiro uso. |
locales | Traduções (en, pt-BR, …). |
Você declara só o que usa. Um plugin mínimo — como o gerado pelo incubator — traz id, name, icon, version, navigation e routes, e nada mais.
apiVersion: o contrato tem versão
O campo opcional apiVersion fixa a versão do contrato de plugin que o manifesto foi escrito para. O runtime recusa um plugin construído para um contrato mais novo do que ele suporta — é o mecanismo que impede um plugin de uma geração futura de rodar meio quebrado numa plataforma antiga. Omitir significa "compatível/legado".
Por que declarativo
O manifesto ser dado (e não código imperativo) é o que dá as três propriedades que sustentam a plataforma:
- Introspecção — a plataforma sabe exatamente o que um plugin contribui sem executá-lo; é assim que o
fayz doctorverifica pré-requisitos e o editor monta seletores. - Simetria — um plugin app-local e um oficial usam o mesmo tipo, então promover um é empacotar, não reescrever.
- Segurança de upgrade — os seams são um contrato versionado; a implementação por trás deles pode mudar livremente.
Próximo: as convenções que mantêm um plugin bem-comportado em Padrões.