Premiers pas

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.12.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

Lorsque vous visitez le panneau d’administration pour la première fois, 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 admin.

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'interface admin 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 unique collection live :

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 de plugins avec la commande suivante :

npx emdash secrets generate

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

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 des commentateurs sont générés et stockés dans la base de données à la première utilisation, vous n’avez donc pas besoin de les configurer. Ne surchargez le secret de preview que si un processus séparé doit vérifier les mêmes tokens que votre site principal, comme montré 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 collections live 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="Accueil">
  <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 types complète, générez les types à partir du schéma de votre base de données :

npx emdash types

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

Prochaines étapes

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

• Concepts fondamentaux — Comprenez comment EmDash fonctionne sous le capot
• Travailler avec le contenu — Apprenez à interroger et rendre le contenu
• Médiathèque — Téléchargez et gérez des images et fichiers
• Créer un blog — Construisez un blog complet avec catégories et tags
• Déployer sur Cloudflare — Mettez votre site en production