xpeditis2.0/WINDOWS-INSTALLATION.md

🪟 Installation sur Windows - Xpeditis

Problème avec npm Workspaces sur Windows

Sur Windows, les workspaces npm peuvent rencontrer des problèmes de symlinks (EISDIR error). Voici la solution.

---

✅ Solution : Installation Séparée par App

Au lieu d'utiliser npm install à la racine, installez les dépendances dans chaque app séparément.

Étape 1 : Supprimer le node_modules racine (si existe)

# Si node_modules existe à la racine
rm -rf node_modules

Étape 2 : Installer les dépendances Backend

cd apps/backend
npm install
cd ../..

Durée : 2-3 minutes Packages installés : ~50 packages NestJS, TypeORM, etc.

Étape 3 : Installer les dépendances Frontend

cd apps/frontend
npm install
cd ../..

Durée : 2-3 minutes Packages installés : ~30 packages Next.js, React, Tailwind, etc.

Étape 4 : Installer les dépendances racine (optionnel)

npm install --no-workspaces

Packages installés : prettier, typescript (partagés)

---

✅ Vérification de l'Installation

Vérifier Backend

cd apps/backend

# Vérifier que node_modules existe
ls node_modules

# Vérifier des packages clés
ls node_modules/@nestjs
ls node_modules/typeorm
ls node_modules/pg

# Essayer de démarrer
npm run dev

Attendu : Le serveur démarre sur le port 4000

Vérifier Frontend

cd apps/frontend

# Vérifier que node_modules existe
ls node_modules

# Vérifier des packages clés
ls node_modules/next
ls node_modules/react
ls node_modules/tailwindcss

# Essayer de démarrer
npm run dev

Attendu : Le serveur démarre sur le port 3000

---

🚀 Démarrage Après Installation

1. Démarrer l'infrastructure Docker

docker-compose up -d

2. Configurer l'environnement

# Backend
cp apps/backend/.env.example apps/backend/.env

# Frontend
cp apps/frontend/.env.example apps/frontend/.env

3. Démarrer le Backend

cd apps/backend
npm run dev

URL : http://localhost:4000/api/v1/health

4. Démarrer le Frontend (nouveau terminal)

cd apps/frontend
npm run dev

URL : http://localhost:3000

---

📝 Scripts Modifiés pour Windows

Comme les workspaces ne fonctionnent pas, utilisez ces commandes :

Backend

# Au lieu de: npm run backend:dev
cd apps/backend && npm run dev

# Au lieu de: npm run backend:test
cd apps/backend && npm test

# Au lieu de: npm run backend:build
cd apps/backend && npm run build

Frontend

# Au lieu de: npm run frontend:dev
cd apps/frontend && npm run dev

# Au lieu de: npm run frontend:test
cd apps/frontend && npm test

# Au lieu de: npm run frontend:build
cd apps/frontend && npm run build

Les deux en parallèle

Option 1 : Deux terminaux

Terminal 1 :

cd apps/backend
npm run dev

Terminal 2 :

cd apps/frontend
npm run dev

Option 2 : PowerShell avec Start-Process

# Backend
Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd apps/backend; npm run dev"

# Frontend
Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd apps/frontend; npm run dev"

---

🔧 Alternative : Utiliser pnpm ou yarn

Si npm continue à poser problème, utilisez pnpm (meilleur support Windows) :

Avec pnpm

# Installer pnpm globalement
npm install -g pnpm

# Installer les dépendances
pnpm install

# Démarrer backend
pnpm --filter backend dev

# Démarrer frontend
pnpm --filter frontend dev

Avec yarn

# Installer yarn globalement
npm install -g yarn

# Installer les dépendances
yarn install

# Démarrer backend
yarn workspace backend dev

# Démarrer frontend
yarn workspace frontend dev

---

✅ Checklist d'Installation Windows

• Docker Desktop installé et démarré
• Node.js v20+ installé
• cd apps/backend && npm install terminé
• cd apps/frontend && npm install terminé
• docker-compose up -d exécuté
• Containers PostgreSQL et Redis en cours d'exécution
• .env files copiés
• Backend démarre sur port 4000
• Frontend démarre sur port 3000
• Health endpoint répond : http://localhost:4000/api/v1/health

---

🐛 Dépannage Windows

Erreur : EBUSY (resource busy or locked)

Cause : Fichiers verrouillés par un processus Windows (antivirus, Windows Defender, etc.)

Solutions :

1. Fermer VSCode et tous les terminals
2. Désactiver temporairement l'antivirus
3. Exclure le dossier node_modules de Windows Defender
4. Réessayer l'installation

Erreur : EISDIR (illegal operation on directory)

Cause : Windows ne supporte pas bien les symlinks npm workspaces

Solution : Utiliser l'installation séparée (cette page)

Erreur : EPERM (operation not permitted)

Cause : Permissions insuffisantes

Solutions :

1. Exécuter PowerShell/CMD en tant qu'administrateur
2. Ou utiliser l'installation séparée (pas besoin d'admin)

Backend ne démarre pas - "Cannot find module"

Cause : node_modules manquant ou incomplet

Solution :

cd apps/backend
rm -rf node_modules package-lock.json
npm install

Frontend ne démarre pas - "Cannot find module 'next'"

Cause : node_modules manquant ou incomplet

Solution :

cd apps/frontend
rm -rf node_modules package-lock.json
npm install

Frontend build fail - "EISDIR: illegal operation on directory, readlink"

Cause : Next.js rencontre un problème avec les symlinks sur Windows lors du build

Erreur complète :

Error: EISDIR: illegal operation on a directory, readlink 'D:\xpeditis2.0\apps\frontend\node_modules\next\dist\pages\_app.js'

Solutions :

Option 1 : Utiliser le mode développement (recommandé pour le développement)

cd apps/frontend
npm run dev  # Fonctionne sans problème

Option 2 : Utiliser WSL2 pour le build de production

# Dans WSL2
cd /mnt/d/xpeditis2.0/apps/frontend
npm run build  # Fonctionne correctement

Option 3 : Build depuis PowerShell avec mode développeur activé

# Activer le mode développeur Windows (une seule fois)
# Paramètres > Mise à jour et sécurité > Pour les développeurs > Mode développeur

# Ensuite:
cd apps/frontend
npm run build

Note : Pour le développement quotidien, utilisez npm run dev qui n'a pas ce problème. Le build de production n'est nécessaire que pour le déploiement.

---

💡 Recommandations pour Windows

1. Utiliser PowerShell Core (v7+)

Plus moderne et meilleur support des outils Node.js :

• Télécharger PowerShell

2. Utiliser Windows Terminal

Meilleure expérience terminal :

• Télécharger Windows Terminal

3. Considérer WSL2 (Windows Subsystem for Linux)

Pour une expérience Linux native sur Windows :

# Installer WSL2
wsl --install

# Installer Ubuntu
wsl --install -d Ubuntu

# Utiliser WSL2 pour le développement
cd /mnt/d/xpeditis2.0
npm install  # Fonctionne comme sur Linux

4. Exclure node_modules de l'antivirus

Pour améliorer les performances :

Windows Defender :

1. Paramètres Windows > Mise à jour et sécurité > Sécurité Windows
2. Protection contre les virus et menaces > Gérer les paramètres
3. Exclusions > Ajouter une exclusion > Dossier
4. Ajouter : D:\xpeditis2.0\node_modules
5. Ajouter : D:\xpeditis2.0\apps\backend\node_modules
6. Ajouter : D:\xpeditis2.0\apps\frontend\node_modules

---

✅ Installation Réussie !

Une fois les dépendances installées dans chaque app :

# Backend
cd apps/backend
npm run dev
# Visiter: http://localhost:4000/api/docs

# Frontend (nouveau terminal)
cd apps/frontend
npm run dev
# Visiter: http://localhost:3000

Tout fonctionne ? Excellent ! 🎉

Passez à NEXT-STEPS.md pour commencer le développement.

---

📞 Besoin d'Aide ?

Si les problèmes persistent :

1. Vérifier Node.js version : node --version (doit être v20+)
2. Vérifier npm version : npm --version (doit être v10+)
3. Essayer avec pnpm : npm install -g pnpm && pnpm install
4. Utiliser WSL2 pour une expérience Linux
5. Consulter INSTALLATION-STEPS.md

---

Xpeditis - Installation Windows Solution pour npm workspaces sur Windows