Distribuir plugins nativos

Los plugins nativos se distribuyen vía npm, no por el marketplace. No hay bundler, ni manifest, ni paso de auditoría de seguridad — solo un paquete npm normal que exporta una factory de descriptores más createPlugin. Los operadores del sitio lo instalan con npm install y lo registran en astro.config.mjs.

Estructura del paquete

Un paquete de plugin nativo típico:

@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"
	}
}

Omite las exportaciones ./admin y ./astro si tu plugin no las necesita.

Configuración de compilación

Los plugins nativos se distribuyen como módulos ES. La mayoría de los autores usan tsdown (o tsup) con TypeScript. Externaliza react, emdash y @emdash-cms/admin para que no se empaqueten en tu salida:

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

Si distribuyes componentes Astro para renderizado de Portable Text, estos no necesitan empaquetado — Astro consume los archivos fuente .astro directamente. Lista el directorio astro/ bajo files para que se incluyan en el tarball de npm.

Versionado

Usa versionado semántico. Incrementar una versión mayor es una señal para los operadores de que pueden necesitar hacer cambios al actualizar. La forma de definePlugin() y la API de contexto del plugin son estables, pero si cambias el comportamiento de hooks de tu plugin, requisitos de capacidad o esquema de configuración de una manera que afecte las instalaciones existentes, eso es un cambio rompedor.

Las capacidades son parte del contrato de superficie del plugin. Agregar una en una versión no mayor significa que los operadores existentes actualizan y otorgan silenciosamente una nueva capacidad — eso está bien para un plugin en sandbox donde el diálogo de consentimiento vuelve a aparecer, pero los plugins nativos no tienen un flujo de consentimiento. Trata las adiciones de capacidad como un bump de versión mayor para plugins nativos, o documéntalas de manera muy prominente en las notas de lanzamiento.

README y documentación

Un buen README de plugin cubre:

• Qué hace el plugin, en una oración.
• Cómo instalarlo (npm install ... y el snippet de astro.config.mjs con el import).
• Qué capacidades declara y para qué las usa.
• Cualquier cambio requerido en la plantilla Astro (p.ej. <EmDashHead /> para page:metadata, <EmDashBodyEnd /> para page:fragments).
• Configuraciones y qué controla cada una.
• Notas de migración entre versiones mayores.

Publicar en npm

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

Para paquetes con scope, --access public es requerido en la primera publicación (npm establece los paquetes con scope como privados por defecto).

Desarrollo local contra un sitio anfitrión

Al iterar en un plugin, enlázalo a un sitio de prueba en lugar de republicar en cada cambio:

# 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

Luego registra el plugin en el astro.config.mjs del sitio de prueba y ejecuta el servidor de desarrollo. Los manejadores de hooks se ejecutan en la siguiente solicitud después de que pnpm build termina.

¿Marketplace? No.

Los plugins nativos no pueden publicarse en el marketplace de EmDash. El marketplace es solo para sandbox: cada plugin publicado pasa por emdash plugin bundle (que valida que el código del backend sea autocontenido, no importe módulos integrados de Node.js y permanezca bajo los límites de tamaño), recibe una auditoría de seguridad y se ejecuta en el runtime sandbox al instalarse.

Si quieres la superficie de distribución del marketplace pero tu plugin actualmente usa características exclusivas de nativos, pregúntate si realmente las necesitas — muchos plugins pueden eliminar page:fragments o convertir de settingsSchema a una página de configuración Block Kit y volverse sandboxeables. Consulta Elegir un formato de plugin para las compensaciones.