Distribuição de plugins nativos

Plugins nativos são distribuídos via npm. Um plugin nativo é um pacote npm comum que exporta uma factory de descriptor mais createPlugin. Operadores do site o instalam com npm install e o registram em astro.config.mjs.

Layout do pacote

Um pacote de plugin nativo típico possui o seguinte layout:

@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

O seguinte package.json declara os scripts de build, exports e peer dependencies que um plugin distribuível precisa:

{
	"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 os exports ./admin e ./astro se seu plugin não precisar deles.

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 major é um sinal aos operadores de que podem precisar fazer mudanças ao atualizar. A forma de definePlugin() e a API de contexto do plugin são estáveis, mas se você mudar o comportamento do hook do seu plugin, requisitos de capacidade ou esquema de configurações de uma forma que afete instalações existentes, isso é uma mudança incompatível.

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

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 astro.config.mjs com a importação).
• Quais capacidades ele declara e para que as usa.
• Quaisquer mudanças necessárias no template Astro (ex: <EmDashHead /> para page:metadata, <EmDashBodyEnd /> para page:fragments).
• Configurações e o que cada uma controla.
• Notas de migração entre versões major.

Publicação no npm

Aumente a versão e publique o pacote:

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

Para pacotes com escopo, --access public é necessário na primeira publicaçã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 mudança:

# 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. Handlers de hook são executados na próxima requisição após pnpm build terminar.

Disponibilidade no marketplace

Plugins nativos não podem ser publicados no marketplace EmDash. O marketplace é exclusivamente para sandbox: cada plugin publicado passa por emdash plugin bundle (que valida que o código do backend é auto-contido, não importa built-ins do Node.js e permanece sob os limites de tamanho), recebe uma auditoria de segurança e executa no runtime de sandbox quando instalado.

Um plugin que usa recursos exclusivos nativos pode às vezes removê-los e tornar-se sandboxable — por exemplo, removendo page:fragments ou convertendo settingsSchema para uma página de configurações Block Kit. Veja Escolhendo um formato de plugin para as compensações.