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

Passer à EmDash 1.0

Sur cette page

EmDash 1.0 supprime les API dépréciées pendant la série 0.x et déplace sous emdash/internal/ les points d’entrée que seul EmDash charge lui-même. Ce guide liste chaque changement majeur et ce qu’il faut mettre à jour dans votre site.

Mettre à jour vos dépendances

Mettez à jour emdash et tous les autres paquets EmDash utilisés par votre site vers leurs dernières versions, puis reconstruisez. L’exemple suivant met à jour un site Cloudflare :

pnpm up --latest emdash @emdash-cms/cloudflare
pnpm build

Si votre déploiement exécute emdash migrate, exécutez-le avec le fichier .emdash/migrations.json produit par un build réalisé après la mise à jour. La commande rejette un manifeste écrit par une version antérieure d’EmDash.

Après la mise à jour, votre site peut se construire et s’exécuter sans autre modification. Si le build échoue ou si EmDash signale une erreur au démarrage, parcourez les changements majeurs ci-dessous.

Pour la liste complète des changements de chaque paquet, consultez son entrée sur la page des versions.

Changements majeurs

Supprimé : cloudflareCache()

Dans les versions précédentes, cloudflareCache() de @emdash-cms/cloudflare fournissait un fournisseur de cache de routes qui purgeait les pages en cache via l’API REST de Cloudflare.

cloudflareCache() et ses points d’entrée @emdash-cms/cloudflare/cache et @emdash-cms/cloudflare/cache/config sont supprimés. Un site qui l’importe ne se construit plus.

Que dois-je faire ?

Remplacez-le par le fournisseur cacheCloudflare() de l’adaptateur Astro pour Cloudflare, qui utilise Workers Cache. L’adaptateur active Workers Cache dans la configuration de déploiement générée lorsque ce fournisseur est défini.

L’exemple suivant montre la modification dans astro.config.mjs :

import { cloudflareCache } from "@emdash-cms/cloudflare";
import { cacheCloudflare } from "@astrojs/cloudflare/cache";

export default defineConfig({
	cache: {
		provider: cloudflareCache(),
		provider: cacheCloudflare(),
	},
});

Workers Cache purge avec cache.purge() depuis cloudflare:workers, vous pouvez donc supprimer les secrets CF_ZONE_ID et CF_CACHE_PURGE_TOKEN de votre Worker. Le cache d’objets KV (kvCache()) reste inchangé.

Supprimé : Comments et CommentForm de emdash/ui

Dans les versions précédentes, les composants Comments et CommentForm étaient exportés à la fois depuis emdash/ui et depuis emdash/ui/comments.

Ils ne sont désormais exportés que depuis emdash/ui/comments. Un site qui importe l’un ou l’autre de ces composants depuis emdash/ui ne se construit plus.

Que dois-je faire ?

Mettez à jour l’import. Les composants eux-mêmes sont inchangés.

---
import { Comments, CommentForm } from "emdash/ui";
import { Comments, CommentForm } from "emdash/ui/comments";
---

Supprimé : emdash dev et emdash auth secret

Dans les versions précédentes, emdash dev démarrait un serveur de développement reposant sur un ./data.db local, et emdash auth secret générait une valeur pour EMDASH_AUTH_SECRET.

Les deux commandes sont supprimées. Exécuter l’une ou l’autre se termine par Unknown command.

Que dois-je faire ?

Remplacez emdash dev par le script de développement propre à votre site, comme pnpm dev, ou exécutez astro dev. Le site utilise alors l’adaptateur de base de données de sa configuration.

Si votre package.json contient une clé url sous emdash, supprimez-la. Pour générer des types depuis un site distant, exécutez emdash types --url <site-url> ou définissez EMDASH_URL.

Retirez emdash auth secret de vos scripts. Si votre site a déjà EMDASH_AUTH_SECRET défini, conservez-le : EmDash le lit toujours afin que les hachages d’adresses IP des commentateurs stockés restent stables. Pour chiffrer les secrets des plugins au repos, générez une clé de chiffrement avec emdash secrets generate.

Supprimé : experimental.registry

Dans les versions précédentes, vous pouviez configurer le registre de plugins avec experimental.registry dans les options de emdash().

L’option est supprimée, ainsi que l’option experimental elle-même. Un site qui définit encore experimental.registry échoue au démarrage avec une erreur qui nomme l’option registry de premier niveau.

Que dois-je faire ?

Déplacez la valeur telle quelle vers l’option registry de premier niveau. Elle accepte la même chaîne d’URL ou le même objet de configuration.

emdash({
	experimental: {
		registry: {
			aggregatorUrl: "https://registry.example.com",
			policy: { minimumReleaseAge: "48h" },
		},
	},
	registry: {
		aggregatorUrl: "https://registry.example.com",
		policy: { minimumReleaseAge: "48h" },
	},
});

S’il vous reste un bloc experimental: {} vide, supprimez-le. Les configurations TypeScript le signalent comme une erreur.

Modifié : les points d’entrée internes déplacés vers emdash/internal/

Dans les versions précédentes, emdash exposait des points d’entrée tels que emdash/routes/*, emdash/middleware/*, emdash/db/sqlite-migrations et emdash/plugin-test-runtime, que seul EmDash charge lui-même.

Ces points d’entrée se trouvent sous emdash/internal/. Il en va de même pour les exécuteurs de migrations D1 et Hyperdrive de @emdash-cms/cloudflare, qui se trouvent sous @emdash-cms/cloudflare/internal/db/. Ils ne font pas partie de l’API publique, et leurs exports peuvent changer à chaque version. Les sites qui configurent EmDash via emdash() dans astro.config.mjs ne sont pas concernés.

Que dois-je faire ?

Si votre projet importe directement l’un de ces chemins, remplacez l’import par l’API publique :

  • Pour configurer une base de données, un cache d’objets ou un fournisseur de médias, utilisez sqlite(), libsql() ou postgres() depuis emdash/db, memoryCache() depuis emdash/astro, ou localMedia() depuis emdash/media.
  • Pour tester un plugin, utilisez @emdash-cms/plugin-test à la place de emdash/plugin-test-runtime.
  • Pour exécuter votre propre middleware avant celui d’EmDash, définissez l’option middleware.outer de emdash().

Les middlewares internes d’authentification, de configuration initiale, de redirection et de contexte de requête n’ont pas de remplacement public.

Dépréciations

Déprécié : anciens noms de capacités de plugins

Dans les versions précédentes, les plugins pouvaient déclarer des capacités sous des noms tels que read:content, network:fetch et page:inject sans aucun avertissement.

EmDash consigne un avertissement au démarrage pour chaque plugin qui déclare l’un de ces noms dépréciés, en indiquant le remplacement actuel de chacun (par exemple read:content → content:read). Les noms dépréciés continuent de fonctionner pendant toute la série 1.x.

Que dois-je faire ?

Si un plugin que vous utilisez déclenche l’avertissement, mettez-le à jour vers une version qui utilise les noms actuels, ou demandez à son auteur d’en publier une. Si vous maintenez le plugin, renommez les capacités dans son manifeste. Consultez Capacités et sécurité pour les noms actuels.