Les plugins EmDash sont livrés dans l’un des deux formats : sandboxed ou native. Le choix affecte la façon dont le plugin est installé, quelle application il obtient à l’exécution et quelles fonctionnalités sont disponibles.
Par défaut, utilisez sandboxed. Les plugins sandboxed peuvent être publiés sur le marketplace et installés depuis l’interface d’administration en un clic. Les plugins natifs nécessitent une modification de code, un npm install et un redéploiement sur chaque site qui les souhaite. Sandboxed est ce que les utilisateurs finaux veulent.
Choisissez native uniquement lorsque vous avez besoin d’une fonctionnalité que le sandbox ne peut pas fournir.
En un coup d’œil
| Sandboxed | Native | |
|---|---|---|
Champ format dans le descripteur | "standard" | "native" |
| Méthode d’installation | Un clic depuis le marketplace d’administration | npm install + éditer astro.config |
| S’exécute dans | Un runtime isolé fourni par un sandbox runner | Le même processus que votre site Astro |
| Capacités | Appliquées par le pont du sandbox | Appliquées en processus par le même pont |
| Limites de ressources | Appliquées par le runner — typiquement CPU, sous-requêtes, temps d’exécution, mémoire | Aucune |
| Accès réseau | ctx.http uniquement, restreint à allowedHosts | ctx.http uniquement, restreint à allowedHosts |
fetch() / process.env direct | Bloqué par le runner | Possible (le code du plugin partage le runtime) |
| Distribution | Bundle .tar.gz sur le marketplace | Paquet npm |
| Interface d’administration | Routes Block Kit (décrites en JSON) | Composants React ou Block Kit |
| Interface de paramètres | Page Block Kit + lectures KV | admin.settingsSchema (formulaire automatique) ou Block Kit |
| Composants de rendu Portable Text | Non disponible | componentsEntry fournit des composants Astro |
| Contributions de métadonnées de page | Hook page:metadata — balises meta/property, rels <link> autorisés, JSON-LD | Hook page:metadata (même surface) |
| Injection de fragments de page | Non disponible — uniquement meta/JSON-LD via page:metadata | Hook page:fragments — scripts inline, scripts externes, HTML brut |
| Options du constructeur | Aucune — lire les paramètres depuis KV à l’exécution | options dans le descripteur |
Ce que vous abandonnez en choisissant native
Les plugins natifs ressemblent à une version plus puissante de la même chose, et ils le sont — mais le coût est élevé :
- Pas de marketplace. Chaque site doit installer votre paquet npm, éditer
astro.config.mjset redéployer. - Pas d’isolation. Un bug dans votre plugin peut planter le processus hôte ou épuiser son budget CPU. Un rejet non géré dans un hook peut faire tomber la requête environnante avec lui.
- Charge de confiance sur l’utilisateur. Les plugins natifs ont le même accès que le site hôte. Les utilisateurs finaux ne peuvent pas les auditer uniquement via des déclarations de capacités.
Si votre plugin peut faire son travail dans le sandbox, il devrait le faire.
Quand choisir native
Il existe trois raisons de choisir native, et elles concernent toutes des fonctionnalités nécessitant une intégration au moment de la construction avec le site hôte :
-
Pages d’administration ou widgets React personnalisés. Les plugins sandboxed décrivent leur interface d’administration avec Block Kit — un schéma JSON que l’administrateur rend au nom du plugin. Si vous avez besoin de React complet (hooks personnalisés, composants tiers, état complexe), vous avez besoin de native.
-
Composants Astro pour rendre les blocs Portable Text sur le site public. Un plugin peut déclarer un type de bloc personnalisé avec
format: "standard", mais les composants Astro qui le rendent sur le site public doivent être chargés au moment de la construction depuis npm. Seuls les plugins natifs peuvent fournir uncomponentsEntry. -
Injecter du HTML brut, des scripts ou des feuilles de style dans les pages publiques. Le hook
page:fragmentsexpédie du code propriétaire vers les navigateurs des visiteurs — en dehors de toute limite de sandbox. Il est réservé aux plugins natifs. Les plugins sandboxed peuvent toujours contribuer aux pages publiques via le hookpage:metadata, qui couvre de nombreux cas d’usage réels :- Balises
meta(name+content) — descriptions SEO, directives robots, Twitter Cards - Balises
property— OpenGraph et autres métadonnées basées sur des propriétés - Balises
linkavec une liste autorisée de rel verrouillée par sécurité (canonical,alternate,author,license,nlweb,site.standard.document) —stylesheet,prefetchet les rels similaires de chargement de ressources ne sont délibérément pas autorisés - Graphes JSON-LD
Si votre besoin « d’injection de page » concerne des données structurées ou des métadonnées SEO, restez en sandboxed et utilisez
page:metadata. Si vous devez réellement expédier du JavaScript ou du HTML vers le navigateur du visiteur, c’est le cas pour choisir native. - Balises
Si vous n’êtes pas sûr, choisissez sandboxed. Vous pouvez toujours migrer vers native plus tard — mais l’inverse est plus difficile, car les fonctionnalités exclusives à native n’ont pas d’équivalent sandbox.
Sandbox runners et support de plateforme
Le sandbox lui-même est pluggable. EmDash expose une option de configuration sandboxRunner et le runner décide comment le code du plugin est isolé — il n’y a rien de spécifique à Cloudflare dans le format du plugin lui-même.
Le runner que la plupart des sites utilisent aujourd’hui est sandbox() de @emdash-cms/cloudflare, qui utilise le Dynamic Worker Loader de Cloudflare Workers. Worker Loader met en cache l’isolat V8 par ID de plugin, de sorte que le coût de démarrage à froid de l’isolat n’est payé qu’une seule fois ; le runner construit un worker stub frais et des bindings de pont à chaque invocation, car les stubs et les bindings sont liés au contexte I/O de la requête appelante. Les runners pour d’autres plateformes (Node.js via workerd et potentiellement Deno) sont en développement.
Si aucun runner n’est configuré, ou si le runner configuré signale qu’il n’est pas disponible sur la plateforme actuelle, les plugins listés sous sandboxed: [] sont ignorés au démarrage avec un log de niveau debug.
Si vous souhaitez qu’un plugin de format standard s’exécute sur une plateforme sans sandbox runner, déplacez-le de sandboxed: [] vers le tableau plugins: [] — il s’exécutera en processus. Les déclarations de capacités sont toujours respectées (la même fabrique PluginContext restreint ctx.content, ctx.http et similaires), mais il n’y a pas de limite d’isolation, pas de limites de ressources, et un plugin bogué ou malveillant peut appeler fetch() directement, lire les variables d’environnement ou bloquer la boucle d’événements. Sans un sandbox runner actif, traitez chaque plugin comme un plugin natif à des fins de confiance.