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 à numéros impairs ne sont pas prises en charge)
• 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

Terminer 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 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 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 de template
│   └── types.ts          # Types TypeScript générés
└── package.json

Fichiers de configuration

astro.config.mjs

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

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

export default defineConfig({
	integrations: [
		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 collection en direct :

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 en tant que EMDASH_ENCRYPTION_KEY, comme indiqué ci-dessous. Cette clé chiffre les secrets de plugins au repos. Définissez-la maintenant pour que votre déploiement soit prêt lorsque 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 tous les secrets chiffrés avec elle.

Le secret HMAC de prévisualisation et le sel de hachage IP du commentateur sont générés et stockés dans la base de données lors de la première utilisation, vous n’avez donc pas besoin de les définir. Remplacez le secret de prévisualisation uniquement si un processus séparé doit vérifier les mêmes jetons 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. Celles-ci suivent le modèle des collections en direct d’Astro, renvoyant { 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 des types TypeScript

Pour une sécurité de type complète, générez des types à partir de votre schéma de base de données :

npx emdash types

Cela 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 type.

Prochaines étapes

Avec le site en cours d’exécution, les pages suivantes couvrent ce qu’il faut faire ensuite :

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