Distribución de plugins nativos

Los plugins nativos se distribuyen a través de npm. Un plugin nativo es un paquete npm regular que exporta una factory de descriptor 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 tiene la siguiente estructura:

@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

El siguiente package.json declara los scripts de compilación, exportaciones y dependencias peer que necesita un plugin distribuible:

{
	"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 incluyan 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 del hook de tu plugin, requisitos de capacidades o esquema de configuración de una manera que afecte las instalaciones existentes, eso es un cambio incompatible.

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 preguntar, pero los plugins nativos no tienen un flujo de consentimiento. Trata las adiciones de capacidades como un incremento de versión mayor para plugins nativos, o documéntalas muy prominentemente 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 fragmento de astro.config.mjs con la importación).
• Qué capacidades declara y para qué las usa.
• Cualquier cambio requerido en la plantilla Astro (ej. <EmDashHead /> para page:metadata, <EmDashBodyEnd /> para page:fragments).
• Configuraciones y qué controla cada una.
• Notas de migración entre versiones mayores.

Publicación en npm

Incrementa la versión y publica el paquete:

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

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

Desarrollo local contra un sitio host

Al iterar en un plugin, vincúlalo 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 termine.

Disponibilidad en el marketplace

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 built-ins de Node.js y permanezca bajo los límites de tamaño), obtiene una auditoría de seguridad y se ejecuta en el runtime de sandbox cuando se instala.

Un plugin que usa características exclusivas nativas a veces puede eliminarlas y volverse sandboxable — por ejemplo, eliminando page:fragments o convirtiendo settingsSchema a una página de configuración de Block Kit. Consulta Elegir un formato de plugin para las compensaciones.