Ajouter EmDash à un projet Astro existant

Ce guide ajoute EmDash à un projet Astro et vérifie l’intégration avec une entrée publiée. Il utilise l’adaptateur Node.js, SQLite et le stockage média local pour que le chemin complet fonctionne sur une seule machine.

Avant de commencer

Utilisez Astro 6 ou ultérieur et Node.js 22.16 ou ultérieur. Vérifiez les deux versions dans le projet :

node --version
npx astro --version

Ce guide change le site vers la sortie server d’Astro et configure l’adaptateur Node.js. Cela change la façon dont le site est construit et déployé. Si le projet utilise déjà un autre adaptateur de serveur, n’en ajoutez pas un second. Conservez cet adaptateur et suivez ses exigences de déploiement ; pour Cloudflare, utilisez le guide Cloudflare Workers.

Committez ou sauvegardez autrement le projet actuel avant de modifier sa configuration.

Installer EmDash

Installez EmDash, l’adaptateur Node.js et le support React :
npm
```
npm install emdash @astrojs/node @astrojs/react react react-dom
```
pnpm
```
pnpm add emdash @astrojs/node @astrojs/react react react-dom
```
yarn
```
yarn add emdash @astrojs/node @astrojs/react react react-dom
```
EmDash utilise React pour le panneau d’administration même quand le site public n’a pas de composants React.

Enregistrez l’adaptateur, React et EmDash dans astro.config.mjs. Si le fichier contient déjà d’autres intégrations ou paramètres, conservez-les et ajoutez les entrées pertinentes de cet exemple :

import node from "@astrojs/node";
import react from "@astrojs/react";
import { defineConfig } from "astro/config";
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",
            }),
        }),
    ],
});

SQLite stocke le contenu et le modèle de contenu dans data.db. L’adaptateur de stockage local écrit les médias dans uploads/ et les sert via la route média d’EmDash. Ajoutez les deux chemins à .gitignore s’ils ne sont pas déjà exclus.

Créez src/live.config.ts pour connecter EmDash au système de contenu d’Astro :
```
import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";

export const collections = {
    _emdash: defineLiveCollection({ loader: emdashLoader() }),
};
```
Si le projet a déjà src/live.config.ts, ajoutez l’entrée _emdash à l’objet collections exporté au lieu de remplacer le fichier. Un src/content.config.ts séparé pour les collections basées sur les fichiers continue de fonctionner en parallèle.
Générez une clé de chiffrement locale et écrivez-la dans .env :
```
npx emdash secrets generate --write .env
```
Confirmez que .env est exclu par .gitignore. La clé protège les secrets des plugins stockés dans la base de données. Remplacer ou perdre la clé rend ces valeurs chiffrées illisibles, conservez donc une sauvegarde protégée avant de déployer le site.

Configurer le site et le contenu

Démarrez le serveur de développement :
```
npm run dev
```
Ouvrez http://localhost:4321/_emdash/admin/. La première visite redirige vers l’assistant de configuration. Entrez les détails du site, créez le compte administrateur et enregistrez un passkey.

Comme ce projet n’a pas de fichier seed, la configuration applique le modèle de départ intégré d’EmDash. Il crée des collections Posts et Pages, des champs Titre et contenu, et des taxonomies Catégorie et Tag. Il n’ajoute pas d’entrées d’exemple.
Ouvrez Posts, sélectionnez New Post et entrez EmDash is connected comme titre. Sélectionnez Save pour créer l’entrée, puis sélectionnez Publish.

La base de données contient maintenant une entrée publiée dans la collection intégrée posts. L’étape suivante la lit depuis une page Astro.

Interroger l’entrée

Créez une page de test rendue côté serveur qui liste les posts publiés :

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

const { entries: posts, error } = await getEmDashCollection("posts");

if (error) {
	throw error;
}
---

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

Ouvrez http://localhost:4321/emdash-test/. La page affiche EmDash is connected. Si vous changez et republiez le titre dans le panneau d’admin, le rechargement de cette page affiche le titre mis à jour.

Pendant le développement local, EmDash génère aussi emdash-env.d.ts à partir du modèle de contenu actuel. Les déclarations générées donnent à TypeScript le nom de la collection posts et son champ title. Ne modifiez pas ce fichier généré manuellement.

Si la vérification échoue

Si l’admin reste sur Loading EmDash…, vérifiez que react() apparaît dans le tableau integrations d’Astro. Installer @astrojs/react sans l’enregistrer ne suffit pas.
Si getEmDashCollection() retourne une erreur sur la collection live, vérifiez que src/live.config.ts exporte _emdash avec emdashLoader().
Si la page fonctionne en développement mais les modifications déployées n’apparaissent pas, vérifiez que la page n’est pas prégénérée et que l’application déployée utilise la sortie serveur.
Si le build ne peut pas résoudre une des importations, relancez la commande d’installation et confirmez que les cinq paquets ont été ajoutés à ce projet plutôt qu’à un autre répertoire du workspace.

Lisez Configuration pour d’autres bases de données, adaptateurs de stockage et options d’authentification. Le guide d’interrogation du contenu couvre les filtres, la pagination, les aperçus et les indices de cache.