Ajouter EmDash à un projet Astro existant

npm create emdash@latest fournit un projet préconfiguré, mais EmDash se greffe aussi sur un site Astro que vous avez déjà. Ce guide parcourt chaque exigence que le template de démarrage gère normalement pour vous — chacune produit une erreur déroutante quand elle manque, alors suivez la liste dans l’ordre.

Prérequis

Astro 6 ou ultérieur — mettez à jour d’abord si vous êtes sur une version majeure plus ancienne (npx @astrojs/upgrade)
Node.js v22.16.0 ou supérieur (les versions impaires ne sont pas supportées)
Sortie serveur — EmDash sert le contenu au runtime, votre projet a donc besoin de output: "server" et d’un adaptateur (Node, Cloudflare, …)

Installer les packages

Installez EmDash avec ses dépendances peer requises. React alimente l’interface d’administration à /_emdash/admin ; il est requis même si votre site lui-même n’utilise pas React.

npm

npm install emdash @astrojs/react react react-dom

pnpm

pnpm add emdash @astrojs/react react react-dom

yarn

yarn add emdash @astrojs/react react react-dom

Déploiement sur Cloudflare ? Ajoutez aussi les packages Cloudflare — le guide Déployer sur Cloudflare les couvre en détail :

npm install @astrojs/cloudflare @emdash-cms/cloudflare

Enregistrer les intégrations

Ajoutez à la fois react() et emdash() à votre tableau integrations. Enregistrer @astrojs/react n’est pas optionnel : installer le package seul ne suffit pas, et sans l’intégration l’admin compile bien mais ne s’hydrate jamais — la page reste sur « Loading EmDash… » indéfiniment.

import { defineConfig } from "astro/config";
import node from "@astrojs/node";
import react from "@astrojs/react";
import emdash, { local } from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
	output: "server",
	adapter: node({ mode: "standalone" }),
	integrations: [
		react(),
		emdash({
			database: sqlite({ url: "file:./data.db" }),
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

Ajouter le loader Live Collections

Créez src/live.config.ts pour que la couche de contenu d’Astro puisse résoudre le contenu EmDash. Sans lui, getEmDashCollection / getEmDashEntry n’ont pas de live collection par laquelle router.

import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";

export const collections = {
	_emdash: defineLiveCollection({ loader: emdashLoader() }),
};

Votre src/content.config.ts existant (collections basées sur des fichiers) continue de fonctionner à côté — voir EmDash pour les développeurs Astro pour la coexistence des deux.

Vérifier l’installation

Démarrez le serveur de développement :
```
npm run dev
```
Ouvrez http://localhost:4321/_emdash/admin et complétez l’assistant de configuration.

Créez et publiez un article, puis interrogez-le depuis une page :

---
import { getEmDashCollection } from "emdash";

const { entries: posts } = await getEmDashCollection("posts", {
	status: "published",
});
---

<ul>{posts.map((post) => <li>{post.data.title}</li>)}</ul>

Déployer sur Cloudflare

Suivez Déployer sur Cloudflare pour la configuration complète (base de données D1, bucket média R2, cron triggers). Deux choses piègent particulièrement les projets existants :

Utilisez Cloudflare Workers, pas Pages. L’adaptateur @astrojs/cloudflare émet un wrangler.json que Pages n’accepte pas. Si votre site se déploie actuellement sur Pages, migrez-le vers Workers d’abord.
Les bindings doivent exister dans votre wrangler.jsonc. Au minimum vous avez besoin d’un binding D1 pour la base de données et d’un binding R2 pour les médias, correspondant aux noms de binding dans votre astro.config.mjs.

Dépannage

Symptôme	Cause	Solution
Admin bloqué sur « Loading EmDash… »	`@astrojs/react` non enregistré	Ajouter `react()` à `integrations`
`Could not resolve "astro:content"` dans `live.config.ts`	Astro antérieur à 6	Mettre à jour Astro
`getEmDashCollection` retourne une erreur	`src/live.config.ts` manquant	Ajouter le loader live collections
Erreurs de build pour packages non résolus	Dépendances peer non installées	Installer `@astrojs/react`, `react`, `react-dom` explicitement
Les changements de contenu n’apparaissent pas	La page est prérenderisée	Définir `export const prerender = false` sur les pages dynamiques

Prochaines étapes

EmDash pour les développeurs Astro — Comment les concepts EmDash se rapportent à ce que vous connaissez déjà
Travailler avec le contenu — Interroger et afficher le contenu
Déployer sur Cloudflare — Mettre le site en production