E EmDash CMS Everything Guides, use cases, plugins, templates
Français

Migration vers la CLI de plugin

Sur cette page

Ce guide s’adresse aux auteurs de plugins sandboxed écrits avec la forme précédente de definePlugin(). Traitez les changements incompatibles dans l’ordre. Aucun d’entre eux ne modifie le comportement de vos hooks ou routes à l’exécution ; ils modifient la façon dont le plugin est déclaré, construit et publié.

Pour la liste complète des changements dans chaque paquet, consultez le changelog d’EmDash.

Changements incompatibles

Renommé : @emdash-cms/registry-cli devient @emdash-cms/plugin-cli

Les versions précédentes livraient la CLI sous le nom @emdash-cms/registry-cli, avec un binaire emdash-registry.

Le paquet s’appelle maintenant @emdash-cms/plugin-cli et le binaire est emdash-plugin. L’ancien paquet n’est plus publié.

Que dois-je faire ?

Remplacez la dépendance :

pnpm remove @emdash-cms/registry-cli
pnpm add -D @emdash-cms/plugin-cli

Remplacez emdash-registry par emdash-plugin partout où vous l’appelez. Chaque sous-commande conserve son nom (bundle, publish, login, whoami, switch, validate), et init, build et dev sont ajoutés. Voir La CLI de plugin.

Modifié : les plugins sandboxed sont définis avec satisfies SandboxedPlugin

Les versions précédentes enveloppaient les hooks et routes du plugin dans definePlugin() importé de emdash, avec les paramètres de chaque gestionnaire annotés manuellement.

Un plugin sandboxed est maintenant une exportation par défaut simple annotée avec satisfies SandboxedPlugin. Le type provient de emdash/plugin, un point d’entrée de types uniquement que le bundler supprime. TypeScript infère event et ctx de chaque gestionnaire à partir du nom du hook ou de la route, donc les paramètres du gestionnaire n’ont pas besoin d’annotations.

Que dois-je faire ?

Effectuez quatre modifications dans le fichier source du plugin. Remplacez l’importation :

import { definePlugin, type ContentHookEvent, type PluginContext } from "emdash";
import type { SandboxedPlugin } from "emdash/plugin";

Remplacez l’enveloppe definePlugin() par un objet simple et une annotation satisfies :

export default definePlugin({ /* hooks, routes */ });
export default { /* hooks, routes */ } satisfies SandboxedPlugin;

Supprimez les annotations de paramètres de chaque gestionnaire :

handler: async (event: ContentHookEvent, ctx: PluginContext) => {
handler: async (event, ctx) => {

Le résultat est un seul objet exporté par défaut :

import type { SandboxedPlugin } from "emdash/plugin";

export default {
	hooks: {
		"content:beforeSave": {
			handler: async (event, ctx) => {
				return event.content;
			},
		},
	},
} satisfies SandboxedPlugin;

Pour nommer un type d’événement dans une fonction auxiliaire, importez-le depuis emdash/plugin :

import type { ContentHookEvent, PluginContext } from "emdash/plugin";

L’event d’un gestionnaire est toujours le type canonique pour ce hook. Annoter un gestionnaire avec une interface plus étroite ne passe plus la vérification de types. Validez tous les champs dont vous dépendez à l’exécution avec une vérification typeof ou un guard, ce qui est l’approche correcte pour les données provenant de l’extérieur du système de types.

Modifié : un plugin est un src/plugin.ts plus emdash-plugin.jsonc

Les versions précédentes divisaient un plugin en deux fichiers : src/index.ts renvoyait un PluginDescriptor (id, version, capabilities, storage, entrypoint), et src/sandbox-entry.ts contenait les hooks et routes.

Un plugin est maintenant un fichier d’exécution, src/plugin.ts (hooks et routes), et un manifeste édité manuellement, emdash-plugin.jsonc (identité et contrat de confiance). Les champs entrypoint et format ont disparu ; la construction les connecte.

Que dois-je faire ?

Déplacez les hooks et routes dans src/plugin.ts en utilisant la forme ci-dessus. Déplacez les métadonnées du descripteur dans emdash-plugin.jsonc à côté de package.json. L’id du descripteur devient le slug du manifeste ; capabilities, allowedHosts et storage conservent leur forme ; version est lu depuis package.json, donc omettez-le.

L’exemple suivant montre l’équivalent manifeste d’un descripteur qui déclarait une collection de stockage :

{
	"$schema": "./node_modules/@emdash-cms/plugin-cli/schemas/emdash-plugin.schema.json",

	"slug": "plugin-hello",
	"publisher": "did:plc:abc123def456",

	"license": "MIT",
	"author": { "name": "Jane Doe", "url": "https://example.com" },
	"security": { "email": "security@example.com" },

	"capabilities": [],
	"allowedHosts": [],
	"storage": { "events": { "indexes": ["timestamp"] } }
}

Voir Le manifeste du plugin pour tous les champs, et Épinglage de l’éditeur pour le champ publisher.

Dans package.json, pointez l’exportation "./sandbox" vers le fichier d’exécution construit :

"./sandbox": "./dist/sandbox-entry.mjs"
"./sandbox": "./dist/plugin.mjs"

Ajoutez le manifeste à files pour qu’il soit livré avec le paquet :

"files": ["dist"]
"files": ["dist", "emdash-plugin.jsonc"]

Modifié : construire avec emdash-plugin build

Les versions précédentes construisaient les deux fichiers source avec un script tsdown écrit manuellement.

emdash-plugin build lit emdash-plugin.jsonc et src/plugin.ts et émet les artefacts dist/. emdash-plugin dev surveille et reconstruit.

Que dois-je faire ?

Remplacez le script de construction et ajoutez un script de surveillance :

"scripts": {
	"build": "tsdown src/index.ts src/sandbox-entry.ts --format esm --dts --clean"
	"build": "emdash-plugin build",
	"dev": "emdash-plugin dev"
}

Ensuite, validez et construisez :

emdash-plugin validate
emdash-plugin build

Supprimé : exportations de types et fonctions de format standard depuis emdash

Les versions précédentes exportaient StandardPluginDefinition, StandardHookHandler, StandardHookEntry, StandardRouteHandler, StandardRouteEntry et la fonction isStandardPluginDefinition depuis emdash.

Ceux-ci sont supprimés. C’étaient des alias d’aide pour la forme précédente de definePlugin.

Que dois-je faire ?

Utilisez SandboxedPlugin de emdash/plugin dans le même but. L’exportation par défaut d’un plugin sandboxed est déjà typée par son annotation satisfies SandboxedPlugin, donc il n’y a pas de remplacement pour isStandardPluginDefinition ; identifiez un plugin par sa structure ({ hooks?, routes? }) si nécessaire.

Renommé : le type d’exécution SandboxedPlugin devient SandboxedPluginInstance

Cela affecte uniquement les auteurs d’un SandboxRunner personnalisé, comme @emdash-cms/cloudflare. La plupart des auteurs de plugins peuvent l’ignorer.

SandboxedPlugin de emdash fait maintenant référence à la forme source orientée auteur. Le handle d’exécution renvoyé par SandboxRunner.load est SandboxedPluginInstance.

Que dois-je faire ?

Si vous importez SandboxedPlugin de emdash pour typer un sandbox runner ou détenir des handles de plugins d’exécution, changez l’importation en SandboxedPluginInstance :

import type { SandboxedPlugin } from "emdash";
import type { SandboxedPluginInstance } from "emdash";

Informez vos utilisateurs

Les sites qui installent votre plugin doivent également modifier leur importation. Indiquez-leur la nouvelle forme : supprimez les accolades et les ().

import { helloPlugin } from "@my-org/plugin-hello";
import hello from "@my-org/plugin-hello";

export default defineConfig({
	integrations: [
		emdash({
			sandboxed: [helloPlugin()],
			sandboxed: [hello],
		}),
	],
});

Si votre plugin acceptait une configuration via sa factory, cette configuration passe aux paramètres de plugin de l’interface d’administration. Lisez-la à l’exécution via ctx.kv ou settings. Voir Paramètres.

Suivant