Distribuer des plugins natifs

Les plugins natifs se distribuent via npm, pas via le marketplace. Il n’y a pas de bundler, pas de manifeste, pas d’étape d’audit de sécurité — juste un package npm classique qui exporte une factory de descripteur plus createPlugin. Les opérateurs de site l’installent avec npm install et l’enregistrent dans astro.config.mjs.

Structure du package

Un package de plugin natif typique :

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

Omettez les exports ./admin et ./astro si votre plugin n’en a pas besoin.

Configuration de build

Les plugins natifs sont distribués sous forme de modules ES. La plupart des auteurs utilisent tsdown (ou tsup) avec TypeScript. Externalisez react, emdash et @emdash-cms/admin pour qu’ils ne soient pas empaquetés dans votre sortie :

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

Si vous distribuez des composants Astro pour le rendu Portable Text, ceux-ci n’ont pas besoin d’empaquetage — Astro consomme directement les fichiers sources .astro. Listez le répertoire astro/ sous files pour qu’ils soient inclus dans le tarball npm.

Versioning

Utilisez le versioning sémantique. Incrémenter une version majeure est un signal aux opérateurs qu’ils devront peut-être apporter des modifications lors de la mise à niveau. La forme de definePlugin() et l’API de contexte du plugin sont stables, mais si vous modifiez le comportement des hooks de votre plugin, les exigences de capacité ou le schéma de paramètres d’une manière qui affecte les installations existantes, c’est un changement cassant.

Les capacités font partie du contrat de surface du plugin. En ajouter une dans une version non majeure signifie que les opérateurs existants mettent à niveau et accordent silencieusement une nouvelle capacité — c’est acceptable pour un plugin en sandbox où la boîte de dialogue de consentement se réaffiche, mais les plugins natifs n’ont pas de flux de consentement. Traitez les ajouts de capacité comme un bump de version majeure pour les plugins natifs, ou documentez-les de manière très visible dans les notes de version.

README et documentation

Un bon README de plugin couvre :

• Ce que fait le plugin, en une phrase.
• Comment l’installer (npm install ... et le snippet astro.config.mjs avec l’import).
• Quelles capacités il déclare et à quoi il les utilise.
• Toutes les modifications de template Astro requises (par ex. <EmDashHead /> pour page:metadata, <EmDashBodyEnd /> pour page:fragments).
• Les paramètres et ce que chacun contrôle.
• Notes de migration entre les versions majeures.

Publication sur npm

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

Pour les packages scopés, --access public est requis lors de la première publication (npm met par défaut les packages scopés en privé).

Développement local contre un site hôte

Lors de l’itération sur un plugin, liez-le à un site de test plutôt que de republier à chaque modification :

# 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

Ensuite, enregistrez le plugin dans le astro.config.mjs du site de test et lancez le serveur de développement. Les gestionnaires de hooks s’exécutent à la prochaine requête après la fin de pnpm build.

Marketplace ? Non.

Les plugins natifs ne peuvent pas être publiés sur le marketplace EmDash. Le marketplace est réservé au sandbox : chaque plugin publié passe par emdash plugin bundle (qui valide que le code backend est autonome, n’importe pas de modules intégrés Node.js et reste sous les limites de taille), reçoit un audit de sécurité et s’exécute dans le runtime sandbox lors de l’installation.

Si vous souhaitez la surface de distribution du marketplace mais que votre plugin utilise actuellement des fonctionnalités réservées aux natifs, demandez-vous si vous en avez réellement besoin — de nombreux plugins peuvent abandonner page:fragments ou convertir de settingsSchema vers une page de paramètres Block Kit et devenir sandboxables. Voir Choisir un format de plugin pour les compromis.