🚀 MERN Starter CLI

Un CLI puissant pour générer instantanément un projet MERN Stack (MongoDB, Express, React, Node.js) complet avec authentification, design moderne et toutes les bonnes pratiques intégrées.

Arrêtez de perdre des heures à reconfigurer la même architecture ! Lancez votre projet en 2 minutes chrono. ⚡

✨ Fonctionnalités

🔧 Backend (Express 5 + TypeScript)

• ✅ TypeScript strict en ESM, du premier au dernier fichier
• ✅ Architecture par couches au contrat clair : routes → validators → controllers → services → repositories → models
• ✅ Auth de niveau production : JWT RS256 (15 min) + refresh tokens opaques hashés et à rotation (30 j), révocables
• ✅ Double canal : en-tête Bearer (mobile) et cookies httpOnly (web), au choix du client
• ✅ RBAC : rôles + permissions relus en base à chaque requête (bannissement à effet immédiat)
• ✅ Vérification d'email et mot de passe oublié par jetons à usage unique (Resend)
• ✅ Anti-énumération de comptes sur login et mot de passe oublié
• ✅ Base de données : MongoDB + Mongoose (index TTL, seed idempotent)
• ✅ 36 tests Vitest + Supertest, sur une base de test dédiée
• ✅ Qualité : ESLint typé, Prettier, husky + lint-staged, CI GitHub Actions
• ✅ Docker : compose dev (Mongo + API + front) et image de production multi-stage

🎨 Frontend (React + Vite)

• ✅ Design moderne : Tailwind CSS v4 + composants shadcn/ui
• ✅ Pages complètes : Login, Register, Dashboard, Profil, Mot de passe oublié / Réinitialisation, Vérification d'email
• ✅ State management : Redux Toolkit
• ✅ Formulaires : React Hook Form + Yup (règles alignées sur les validators du serveur)
• ✅ Notifications : React Hot Toast avec design élégant
• ✅ Routing : React Router avec routes protégées (Public/Private)
• ✅ Session sécurisée : access token en mémoire (jamais dans localStorage), refresh automatique sur 401 et restauration de session au démarrage
• ✅ Toutes les APIs déjà connectées et fonctionnelles

📦 Installation

npm install -g mern-starter-cli

🚀 Utilisation

mern-starter-cli create

Le CLI vous demandera le nom de votre projet, puis :

1. ✅ Créera la structure complète (client/ + server/) et le dépôt git
2. ✅ Installera toutes les dépendances
3. ✅ Mettra à jour les packages vers les dernières versions avec ncu
4. ✅ Configurera Tailwind CSS v4 + shadcn/ui
5. ✅ Copiera tous les templates pré-configurés
6. ✅ Générera vos clés JWT RS256 et le .env du backend — rien à configurer à la main

Prérequis : Node.js ≥ 22, et une base MongoDB (locale, Atlas, ou celle du docker compose fourni).

📁 Structure du projet généré

mon-projet/
├── client/                      # 🎨 Frontend React
│   ├── src/
│   │   ├── api/                # Services API
│   │   │   └── auth.js
│   │   ├── components/         # Composants UI (shadcn/ui)
│   │   │   └── ui/
│   │   ├── lib/                # Utilitaires
│   │   │   ├── axios.js        # Configuration Axios
│   │   │   └── utils.js
│   │   ├── pages/              # Pages de l'application
│   │   │   ├── Login.jsx
│   │   │   ├── Register.jsx
│   │   │   ├── Dashboard.jsx
│   │   │   ├── Profile.jsx
│   │   │   ├── ForgotPassword.jsx
│   │   │   ├── ResetPassword.jsx
│   │   │   └── VerifyEmail.jsx
│   │   ├── schemas/            # Schémas de validation Yup
│   │   │   ├── login.schema.js
│   │   │   ├── register.schema.js
│   │   │   └── ...
│   │   ├── slices/             # Redux slices
│   │   │   └── authSlice.js
│   │   ├── store/              # Redux store
│   │   │   └── store.js
│   │   ├── App.jsx
│   │   └── main.jsx
│   ├── .npmrc                  # Configuration npm
│   ├── .env / .env.example
│   ├── jsconfig.json           # Alias @ configuré
│   ├── vite.config.js
│   └── package.json
│
└── server/                      # 🔧 Backend Express 5 + TypeScript
    ├── src/
    │   ├── config/mongoose.ts  # Connexion + synchronisation des index
    │   ├── constants/          # ROLES, PERMISSIONS, durées, cookies, statuts
    │   ├── models/             # Schémas Mongoose (utilisateur, rôle, jeton, session)
    │   ├── repositories/       # Seul endroit qui interroge Mongoose
    │   ├── services/           # Toute la logique métier
    │   ├── controllers/        # Traduction HTTP ⇄ métier
    │   ├── routes/             # URL + middlewares (index = table des matières)
    │   ├── validators/         # express-validator (422)
    │   ├── dtos/               # Formes d'entrée/sortie (jamais de passwordHash)
    │   ├── middlewares/        # jwt · role · permission · validation · erreurs
    │   ├── exceptions/         # Erreurs métier typées → statuts HTTP
    │   ├── utils/              # bcrypt · JWT · jetons SHA-256 · email
    │   ├── app.ts              # Application Express (n'écoute pas)
    │   └── index.ts            # Point d'entrée (connexion + listen)
    ├── tests/                  # Vitest + Supertest (36 tests)
    ├── scripts/                # seed.ts · generer-cles.js
    ├── .github/workflows/ci.yml
    ├── .husky/pre-commit
    ├── Dockerfile · docker-compose.yml · docker-compose.prod.yml
    ├── eslint.config.js · .prettierrc · tsconfig.json · vitest.config.ts
    ├── .env / .env.example
    ├── README.md               # Architecture, conventions et pièges
    └── package.json

🔧 Configuration et démarrage

Le .env du backend est déjà généré par le CLI (clés JWT RS256 comprises) : il n'y a rien à remplir avant de démarrer.

1️⃣ Backend

Avec Docker — base MongoDB incluse, rien d'autre à installer :

cd mon-projet/server
docker compose up --build            # base + API (hot reload)
docker compose --profile client up   # + le front React

Sans Docker — avec un MongoDB local ou Atlas :

cd mon-projet/server

# Ajuster MONGODB_URI dans .env si votre base n'est pas sur localhost:27017
npm run db:seed    # crée les rôles et permissions (rejouable sans risque)
npm run dev

Variables d'environnement Backend (.env) :

NOM_APPLICATION="Mon App"
PORT=5000
COOKIE_SECRET=<généré par le CLI>
MONGODB_URI="mongodb://localhost:27017/mon_app"
MONGO_USER=app                  # utilisés par docker compose
MONGO_PASSWORD=app_dev
MONGO_DB=mon_app
JWT_PRIVATE_KEY="<généré par le CLI>"   # RS256, PEM aplati
JWT_PUBLIC_KEY="<généré par le CLI>"
CLIENT_URLS=http://localhost:5173       # origines autorisées par le CORS
# RESEND_API_KEY=                        # optionnel : sans clé, les emails
# EMAIL_EXPEDITEUR=                      # s'affichent dans les logs

2️⃣ Frontend

cd mon-projet/client
npm run dev

Variables d'environnement Frontend (.env) :

VITE_API_URL=http://localhost:5000

3️⃣ Accéder à l'application

• Frontend : http://localhost:5173
• Backend API : http://localhost:5000
• État de santé (API + base) : http://localhost:5000/health

📚 Routes API disponibles

Toutes préfixées par /api/v1.

| Méthode | Route | Description | Auth | | ------- | ---------------------------------- | ------------------------------------ | ---- | | POST | /auth/register | Créer un compte (rôle client) | ❌ | | POST | /auth/login | Se connecter | ❌ | | POST | /auth/refresh | Renouveler les tokens (rotation) | ❌ | | POST | /auth/logout | Révoquer la session | ❌ | | POST | /auth/verifier-email | Valider l'adresse (jeton reçu) | ❌ | | POST | /auth/mot-de-passe-oublie | Demander un lien de réinitialisation | ❌ | | POST | /auth/reinitialiser-mot-de-passe | Choisir un nouveau mot de passe | ❌ | | GET | /auth/moi | Profil + permissions | ✅ | | PATCH | /auth/moi | Mettre à jour le profil | ✅ | | POST | /auth/changer-mot-de-passe | Changer le mot de passe | ✅ | | POST | /auth/renvoyer-verification | Renvoyer l'email de vérification | ✅ | | GET | /admin/ping | Route témoin (rôle admin) | 🔒 | | GET | /admin/stats | Compteurs (permission dédiée) | 🔒 |

🧪 Tests

cd mon-projet/server

npm test           # 36 tests (unitaires + API)
npm run test:watch # en continu
npm run typecheck  # vérification des types
npm run lint       # ESLint

Les tests tournent sur une base <votre_base>_test, créée et seedée automatiquement : votre base de développement n'est jamais touchée.

📦 Packages principaux inclus

Backend

• express 5 - Framework web (propagation native des erreurs async)
• typescript + tsx - Typage strict et exécution directe en dev
• mongoose - ODM MongoDB
• bcryptjs - Hachage de mots de passe (12 tours)
• jsonwebtoken - JWT signés en RS256
• express-validator - Validation des entrées
• helmet - Sécurité HTTP headers
• cors + cookie-parser - CORS avec cookies httpOnly
• morgan - Logging HTTP
• resend - Envoi d'emails
• vitest + supertest - Tests
• eslint + prettier + husky - Qualité et hooks de commit

Frontend

• react + react-dom - Framework UI
• vite - Build tool ultra-rapide
• tailwindcss - Framework CSS
• shadcn/ui - Composants UI modernes
• react-router-dom - Routing
• @reduxjs/toolkit - State management
• react-redux - Bindings Redux pour React
• axios - Client HTTP
• react-hook-form - Gestion de formulaires
• yup - Validation de schémas
• react-hot-toast - Notifications

🎯 Fonctionnalités clés

🔐 Authentification complète

• Inscription avec validation et email de vérification
• Connexion par JWT RS256, avec refresh tokens à rotation
• Routes protégées par rôle et par permission
• Gestion du profil utilisateur (changer d'email redemande une vérification)
• Changement de mot de passe (déconnecte les autres appareils)
• Réinitialisation par email, jeton à usage unique

🎨 Design moderne

• Interface responsive (mobile-first)
• Composants shadcn/ui personnalisables
• Animations fluides
• Dark mode ready (Tailwind CSS)

🛡️ Sécurité

• Mots de passe hashés avec bcryptjs (12 tours), jamais renvoyés par l'API
• JWT signés en RS256 (clé privée pour signer, publique pour vérifier), portant uniquement l'id
• Refresh tokens opaques stockés hashés en SHA-256 : une fuite de la base ne permet pas de les rejouer
• Rotation des refresh tokens : un token rejoué est refusé
• Cookies httpOnly + sameSite: lax (anti-XSS et anti-CSRF), le refresh limité au chemin d'auth
• Rôle et statut du compte relus en base à chaque requête : un bannissement est immédiat
• Réponses identiques que l'email existe ou non (anti-énumération de comptes)
• Headers sécurisés avec Helmet, CORS restreint à une liste d'origines

⚡ Performance et robustesse

• Index MongoDB déclarés dans les schémas et synchronisés au démarrage
• Index TTL : jetons et sessions expirés purgés automatiquement
• Opérations atomiques sur les jetons à usage unique (pas de double consommation)
• Arrêt propre du serveur (SIGINT/SIGTERM)
• Optimisation Vite, hot reload configuré même dans Docker sous Windows

🤝 Contribution

Les contributions sont les bienvenues ! Voici comment contribuer :

1. 🍴 Fork le projet
2. 🌿 Créer une branche (git checkout -b feature/AmazingFeature)
3. 💾 Commit vos changements (git commit -m 'Add some AmazingFeature')
4. 📤 Push vers la branche (git push origin feature/AmazingFeature)
5. 🔀 Ouvrir une Pull Request

🐛 Rapporter un bug

Ouvrez une issue avec :

• Description du problème
• Étapes pour reproduire
• Comportement attendu vs comportement actuel
• Captures d'écran si applicable

📄 Licence

MIT © Perrin Emmanuel Nzaou

👨‍💻 Auteur

Perrin Emmanuel NZAOU - Développeur Web Full-Stack

• LinkedIn : Perrin Emmanuel Nzaou
• GitHub : @pnzaou
• Portfolio : Perrin Emmanuel Nzaou

⭐ Support

Si ce projet vous aide, donnez-lui une ⭐ !

Créé avec ❤️ pour la communauté des développeurs MERN