Démarrage rapide

Ce guide vous accompagne dans la création de votre premier site EmDash, de l’installation à la publication de votre premier article.

Prérequis

• Node.js v22.16.0 ou supérieur (les versions impaires ne sont pas supportées)
• npm, pnpm ou yarn
• Un éditeur de code (VS Code recommandé)

Créer un nouveau projet

npm create emdash@latest

pnpm create emdash@latest

yarn create emdash

Suivez les invites pour nommer votre projet et configurer vos préférences.

Démarrer le serveur de développement

Compléter l’assistant de configuration

Lors de votre première visite du panneau d’administration, l’assistant de configuration d’EmDash vous guide à travers la configuration initiale :

Une fois votre passkey enregistré, vous êtes connecté et redirigé vers le tableau de bord d’administration.

Votre premier article

Structure du projet

Votre projet EmDash suit une structure Astro standard avec quelques ajouts :

my-emdash-site/
├── astro.config.mjs      # Configuration Astro + EmDash
├── src/
│   ├── live.config.ts    # Configuration des Live Collections
│   ├── pages/
│   │   ├── index.astro   # Page d'accueil
│   │   └── posts/
│   │       └── [...slug].astro  # Pages d'articles dynamiques
│   ├── layouts/
│   │   └── Base.astro    # Layout de base
│   └── components/       # Vos composants Astro
├── .emdash/
│   ├── seed.json         # Fichier seed du template
│   └── types.ts          # Types TypeScript générés
└── package.json

Fichiers de configuration

astro.config.mjs

La configuration suivante enregistre EmDash comme intégration Astro avec une base de données SQLite locale et un stockage de fichiers local :

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

export default defineConfig({
	integrations: [
		react(), // Requis — l'UI d'administration est une app React
		emdash({
			database: sqlite({ url: "file:./data.db" }),
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

src/live.config.ts

Le fichier suivant connecte EmDash au système de contenu d’Astro via une seule live collection :

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

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

Variables d’environnement

Pour la production, générez une clé de chiffrement pour les secrets des plugins avec la commande suivante :

npx emdash secrets generate

Ajoutez la valeur générée à votre environnement en tant que EMDASH_ENCRYPTION_KEY, comme indiqué ci-dessous. Cette clé chiffre les secrets des plugins au repos. Définissez-la maintenant pour que votre déploiement soit prêt quand le chiffrement des secrets de plugins l’utilisera.

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_...

La clé n’est jamais stockée dans la base de données — seul le texte chiffré l’est. Sauvegardez-la dans un endroit durable, car la perdre signifie perdre chaque secret chiffré avec elle.

Le secret HMAC de preview et le sel de hachage d’IP du commentateur sont générés et stockés dans la base de données au premier usage, vous n’avez donc pas besoin de les définir. Surchargez le secret de preview uniquement si un processus séparé doit vérifier les mêmes tokens que votre site principal, comme indiqué ci-dessous.

EMDASH_PREVIEW_SECRET=your-preview-secret

Interroger le contenu dans les pages

Utilisez les fonctions de requête d’EmDash dans vos pages Astro. Elles suivent le modèle des live collections d’Astro, retournant { entries, error } pour les collections et { entry, error } pour les entrées individuelles :

---
import { getEmDashCollection } from "emdash";
import Base from "../layouts/Base.astro";

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

<Base title="Home">
  <h1>Derniers articles</h1>
  <ul>
    {posts.map((post) => (
      <li>
        <a href={`/posts/${post.slug}`}>{post.data.title}</a>
      </li>
    ))}
  </ul>
</Base>

La page suivante récupère une entrée individuelle par slug :

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

const { slug } = Astro.params;
const { entry: post } = await getEmDashEntry("posts", slug);

if (!post) {
  return Astro.redirect("/404");
}
---

<h1>{post.data.title}</h1>

Générer les types TypeScript

Pour une sécurité de typage complète, générez les types depuis votre schéma de base de données :

npx emdash types

Ceci crée .emdash/types.ts avec des interfaces pour toutes vos collections. Votre éditeur complétera automatiquement les noms de champs et détectera les erreurs de types.

Prochaines étapes

Avec le site en fonctionnement, les pages suivantes couvrent la suite :

• Concepts fondamentaux — Comprendre comment EmDash fonctionne en interne
• Travailler avec le contenu — Apprendre à interroger et afficher le contenu
• Bibliothèque de médias — Télécharger et gérer images et fichiers
• Créer un blog — Construire un blog complet avec catégories et tags
• Déployer sur Cloudflare — Mettre votre site en production