Distribuir plugins nativos

Plugins nativos são distribuídos via npm, não pelo marketplace. Não há bundler, nem manifest, nem etapa de auditoria de segurança — apenas um pacote npm normal que exporta uma factory de descritores mais createPlugin. Os operadores do site o instalam com npm install e o registram em astro.config.mjs.

Estrutura do pacote

Um pacote típico de plugin nativo:

@my-org/plugin-analytics/
├── src/
│   ├── index.ts          # Descriptor + createPlugin
│   ├── admin.tsx         # React admin components (optional)
│   └── astro/            # Astro components for PT block rendering (optional)
│       └── index.ts
├── dist/                 # build output
├── package.json
├── tsconfig.json
└── README.md

package.json

{
	"name": "@my-org/plugin-analytics",
	"version": "0.1.0",
	"type": "module",
	"main": "dist/index.js",
	"exports": {
		".": {
			"types": "./dist/index.d.ts",
			"import": "./dist/index.js"
		},
		"./admin": {
			"types": "./dist/admin.d.ts",
			"import": "./dist/admin.js"
		},
		"./astro": {
			"types": "./dist/astro/index.d.ts",
			"import": "./dist/astro/index.js"
		}
	},
	"files": ["dist"],
	"scripts": {
		"build": "tsdown src/index.ts src/admin.tsx --format esm --dts --clean",
		"prepublishOnly": "pnpm build"
	},
	"peerDependencies": {
		"emdash": "*",
		"react": "^18.0.0"
	}
}

Pule as exportações ./admin e ./astro se seu plugin não precisar delas.

Configuração de build

Plugins nativos são distribuídos como módulos ES. A maioria dos autores usa tsdown (ou tsup) com TypeScript. Externalize react, emdash e @emdash-cms/admin para que não sejam empacotados em sua saída:

export default {
	entry: {
		index: "src/index.ts",
		admin: "src/admin.tsx",
	},
	format: "esm",
	dts: true,
	external: ["react", "react-dom", "emdash", "@emdash-cms/admin"],
};

Se você distribuir componentes Astro para renderização de Portable Text, eles não precisam de empacotamento — Astro consome os arquivos fonte .astro diretamente. Liste o diretório astro/ em files para que sejam incluídos no tarball do npm.

Versionamento

Use versionamento semântico. Aumentar uma versão principal é um sinal para os operadores de que eles podem precisar fazer alterações ao atualizar. A forma de definePlugin() e a API de contexto do plugin são estáveis, mas se você alterar o comportamento dos hooks do seu plugin, requisitos de capacidade ou esquema de configurações de uma forma que afete instalações existentes, isso é uma mudança que quebra compatibilidade.

Capacidades são parte do contrato de superfície do plugin. Adicionar uma em uma versão não principal significa que operadores existentes atualizam e silenciosamente concedem uma nova capacidade — isso é aceitável para um plugin sandbox onde o diálogo de consentimento reaparece, mas plugins nativos não têm um fluxo de consentimento. Trate adições de capacidade como um bump de versão principal para plugins nativos, ou documente-as de forma muito proeminente nas notas de lançamento.

README e documentação

Um bom README de plugin cobre:

• O que o plugin faz, em uma frase.
• Como instalá-lo (npm install ... e o snippet de astro.config.mjs com o import).
• Quais capacidades ele declara e para que as usa.
• Quaisquer alterações necessárias no template Astro (por ex. <EmDashHead /> para page:metadata, <EmDashBodyEnd /> para page:fragments).
• Configurações e o que cada uma controla.
• Notas de migração entre versões principais.

Publicar no npm

npm version patch     # or minor/major
npm publish --access public

Para pacotes com escopo, --access public é necessário na primeira publicação (o npm define pacotes com escopo como privados por padrão).

Desenvolvimento local contra um site host

Ao iterar em um plugin, vincule-o a um site de teste em vez de republicar a cada alteração:

# In the plugin package
pnpm build --watch

# In the test site
pnpm add file:../plugins/my-plugin
# or with workspaces:
pnpm add @my-org/plugin-analytics --workspace

Em seguida, registre o plugin no astro.config.mjs do site de teste e execute o servidor de desenvolvimento. Os manipuladores de hooks são executados na próxima solicitação após pnpm build terminar.

Marketplace? Não.

Plugins nativos não podem ser publicados no marketplace EmDash. O marketplace é apenas para sandbox: todo plugin publicado passa por emdash plugin bundle (que valida que o código backend é autocontido, não importa módulos nativos do Node.js e permanece dentro dos limites de tamanho), recebe uma auditoria de segurança e é executado no runtime sandbox quando instalado.

Se você deseja a superfície de distribuição do marketplace, mas seu plugin atualmente usa recursos exclusivos de nativos, pergunte-se se você realmente precisa deles — muitos plugins podem eliminar page:fragments ou converter de settingsSchema para uma página de configurações Block Kit e se tornar sandboxáveis. Veja Escolhendo um formato de plugin para as compensações.