Amorçage de projet et arborescence EmDash CMS

Publié le 2026-04-08 par Emdash Cms Everything

À qui s’adresse ce guide

Utilisez ce guide lorsque vous partez d’un dépôt vide et voulez une structure de répertoires capable de supporter :

• des changements de contenu éditorial quotidiens
• l’itération frontend sans casser les hypothèses du CMS
• un déploiement ultérieur du développement local vers Cloudflare

L’objectif n’est pas l’arborescence la plus astucieuse. L’objectif est de réduire le coût de maintenance à long terme.

Commencer par le choix de runtime

Avant de créer des fichiers, décidez pour quel runtime vous optimisez dans les 30 à 90 prochains jours :

• Node.js + SQLite pour l’embarquement local le plus rapide et la complexité opérationnelle la plus faible
• Cloudflare Workers + D1 + R2 pour le SSR en production, le stockage géré et une intégration plus étroite avec le modèle de plugins EmDash

Si votre équipe valide encore la stratégie de contenu, commencez par Node.js tout en gardant dès le jour un nommage prêt pour Cloudflare. Cela évite un verrouillage plateforme précoce tout en gardant une migration simple.

Arborescence de base recommandée

your-emdash-site/
├── src/
│   ├── components/            # Composants UI réutilisables uniquement
│   ├── layouts/               # Enveloppes de page partagées
│   ├── pages/                 # Routes Astro
│   ├── lib/                   # Logique métier et intégrations
│   ├── styles/                # Styles globaux et jetons partagés
│   └── live.config.ts         # Mapping des collections de contenu live
├── seed/                      # Données de départ pour bootstrap / démo
├── public/                    # Assets statiques (favicons, images statiques)
├── docs/                      # Doc produit et contenu éditorial (MDX)
├── astro.config.mjs
├── package.json
├── tsconfig.json
└── emdash-env.d.ts

Si votre projet existant utilise déjà utils/ au lieu de lib/, gardez-le pour l’instant. Renommez seulement lorsque vous pouvez imposer des règles de propriété claires.

Modèle de propriété des répertoires

La structure ne fonctionne que si la propriété est explicite :

• src/components : unités purement présentation ; pas d’appels directs base de données ou stockage
• src/layouts : cadre partagé (balises head, cadre nav, enveloppe pied de page)
• src/pages : composition des routes et câblage des données pour le rendu
• src/lib : règles métier, adaptateurs de données et colle spécifique plateforme
• seed : contenu de base reproductible pour les nouveaux environnements

Cette séparation évite la dérive la plus courante : le code utilitaire qui devient silencieusement de la logique métier.

Parcours d’amorçage qui limite les retouches

Pour les projets de production, suivez cette séquence :

1. Créer avec le scaffold officiel
2. Choisir un modèle (blog, marketing ou portfolio)
3. Conserver les conventions générées sauf conflit avec une norme d’équipe claire
4. N’ajouter qu’une personnalisation structurelle à la fois

Pourquoi cet ordre : la plupart des retards de lancement ne viennent pas de fonctionnalités manquantes. Ils viennent d’une divergence structurelle précoce qui casse ensuite docs, scripts et embarquement.

Commandes d’amorçage recommandées

# Générer un nouveau projet Emdash CMS
npm create emdash@latest my-emdash-site
cd my-emdash-site

# Installer et lancer le développement local
npm install
npm run dev

Anti-patterns courants à éviter

1) Coder les routes avant les décisions de modèle de contenu

Construire les routes de pages avant d’accorder sur la forme des collections et de la taxonomie provoque des réécritures coûteuses.

2) Mélanger les sujets de déploiement dans les dossiers UI

Ne placez pas les scripts et helpers de config spécifiques au déploiement sous components ou pages. Gardez les sujets plateforme dans les fichiers de config et src/lib.

3) Dossiers utils sans limite

Si tout part dans utils, la découvrabilité s’effondre. Préférez des domaines nommés dans src/lib, par exemple src/lib/content, src/lib/media et src/lib/auth.

Définition du « terminé » pour la mise en place initiale

Considérez l’amorçage comme terminé seulement si tous les contrôles passent :

• le serveur de dev local tourne sans correctifs manuels
• un flux de contenu d’exemple fonctionne de bout en bout
• les données seed peuvent être importées dans un environnement neuf
• le build CI passe sans bricolage spécifique à l’environnement
• un nouveau contributeur peut parcourir le dépôt en moins de dix minutes

Suite logique

Une fois la structure stable :

1. documenter le choix de runtime et les critères de migration dans le dépôt
2. définir les conventions de nommage des types de contenu avant que le volume ne croisse
3. implémenter le runbook de déploiement pour votre plateforme choisie

L’arborescence est de l’architecture, pas du cosmétique. La figer tôt fait gagner des semaines plus tard.