|
|
@@ -0,0 +1,244 @@
|
|
|
+# 1. Unification du frontend sur JavaScript avec Vue.js ou Stimulus
|
|
|
+
|
|
|
+**Date** : 2024-11-08
|
|
|
+**Statut** : Accepté
|
|
|
+**Auteurs** : François
|
|
|
+**Décision** : Standardiser tout le code frontend sur JavaScript pur avec **Vue.js** ou **Stimulus** uniquement.
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Contexte et justification de la décision
|
|
|
+
|
|
|
+Le projet utilise actuellement un mélange de technologies frontend :
|
|
|
+- Composants Stimulus (visible dans les commits récents : remplacement de `bootstrap-star-rating`)
|
|
|
+- Intégration de Webpack et assets modernes (commit `6749285`)
|
|
|
+- Recettes Twig bundle et Stimulus (commit `cdc3c29`, `8034da3`)
|
|
|
+
|
|
|
+**Problèmes identifiés** :
|
|
|
+- **Hétérogénéité technique** : présence de dépendances jQuery et plugins tiers (ex: `bootstrap-star-rating`)
|
|
|
+- **Maintenance complexe** : gestion de multiples stacks frontend
|
|
|
+- **Incohérence d'expérience** : comportements différents selon les composants
|
|
|
+- **Dette technique** : accumulation de code legacy difficile à maintenir
|
|
|
+
|
|
|
+**Besoin** : Uniformiser l'approche frontend pour :
|
|
|
+- Simplifier la maintenance et l'onboarding des développeurs
|
|
|
+- Garantir une expérience utilisateur cohérente
|
|
|
+- Faciliter les tests et le débogage
|
|
|
+- Préparer une migration progressive vers une architecture moderne
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Décision
|
|
|
+
|
|
|
+**Nous adoptons comme standard unique pour le frontend** :
|
|
|
+
|
|
|
+✅ **Autorisés** :
|
|
|
+- **Vue.js** (3.x) - Pour les composants complexes avec état réactif
|
|
|
+- **Stimulus** - Pour les composants légers et l'enrichissement de HTML existant
|
|
|
+- **JavaScript Vanilla** - Pour les scripts simples sans framework
|
|
|
+- **Bootstrap JavaScript** (Popper.js, Tooltips, Popovers, Dropdowns, Modals) - Composants dynamiques natifs autorisés
|
|
|
+
|
|
|
+❌ **Interdits** (dépréciés) :
|
|
|
+- jQuery et ses plugins
|
|
|
+- Tout autre framework/librairie frontend non approuvée
|
|
|
+- Code jQuery existant doit être migré vers Stimulus/Vue
|
|
|
+- Pas de nouveaux plugins jQuery
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Conséquences
|
|
|
+
|
|
|
+### Positives
|
|
|
+
|
|
|
+✅ **Simplification** :
|
|
|
+- Une seule stack JavaScript à maîtriser
|
|
|
+- Moins de conflits de dépendances
|
|
|
+- Build plus simple (Webpack optimisé pour Vue/Stimulus)
|
|
|
+
|
|
|
+✅ **Maintenabilité** :
|
|
|
+- Code plus facile à comprendre et modifier
|
|
|
+- Meilleure intégration avec Symfony (via Webpack Encore)
|
|
|
+- Tests unitaires plus simples à écrire
|
|
|
+
|
|
|
+✅ **Performance** :
|
|
|
+- Bundles JavaScript plus légers (pas de jQuery)
|
|
|
+- Bootstrap 5 JS est léger et tree-shakeable
|
|
|
+- Meilleure optimisation globale
|
|
|
+- Chargement plus rapide des pages
|
|
|
+
|
|
|
+✅ **Évolutivité** :
|
|
|
+- Préparation pour une migration vers une SPA si besoin
|
|
|
+- Intégration facile avec des API REST/GraphQL
|
|
|
+- compatibilité avec les bonnes pratiques modernes
|
|
|
+
|
|
|
+### Négatives
|
|
|
+
|
|
|
+⚠️ **Migration nécessaire** :
|
|
|
+- Tout le code jQuery existant doit être réécrit
|
|
|
+- Certains plugins tiers devront être remplacés par des équivalents Vue/Stimulus
|
|
|
+- Temps d'adaptation pour l'équipe sur Stimulus/Vue
|
|
|
+
|
|
|
+⚠️ **Courbe d'apprentissage** :
|
|
|
+- Stimulus a une approche différente de jQuery
|
|
|
+- Vue.js nécessite une compréhension de la réactivité
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Alternatives envisagées
|
|
|
+
|
|
|
+### 1. Garder jQuery + Ajouter Vue.js/Stimulus
|
|
|
+**Rejetée car** :
|
|
|
+- Maintenir deux stacks en parallèle complexe
|
|
|
+- Conflits potentiels entre bibliothèques
|
|
|
+- Pas de gain significatif en cohérence
|
|
|
+
|
|
|
+### 2. Passer à React
|
|
|
+**Rejetée car** :
|
|
|
+- Intégration plus complexe avec Symfony
|
|
|
+- Courbe d'apprentissage plus raide
|
|
|
+- Surdimensionné pour les besoins actuels
|
|
|
+- Moins adapté pour l'enrichissement progressif de pages serveur
|
|
|
+
|
|
|
+### 3. Passer à Svelte
|
|
|
+**Rejetée car** :
|
|
|
+- Écosystème moins mature dans la communauté Symfony
|
|
|
+- Moins de ressources et tutoriels pour l'intégration
|
|
|
+- Équipe moins familière avec cette technologie
|
|
|
+
|
|
|
+### 4. Garder le statu quo
|
|
|
+**Rejetée car** :
|
|
|
+- Dette technique continue à croître
|
|
|
+- Difficulté croissante à recruter/maintenir
|
|
|
+- Expérience utilisateur incohérente
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Exceptions et clarifications
|
|
|
+
|
|
|
+### Bootstrap JavaScript autorisé
|
|
|
+Les composants **natifs** de Bootstrap JavaScript (basés sur Popper.js) sont **autorisés** car :
|
|
|
+- Ils sont légers et bien intégrés
|
|
|
+- Ils ne dépendent pas de jQuery (depuis Bootstrap 5)
|
|
|
+- Ils couvrent des besoins courants (tooltips, modals, dropdowns) sans réinventer la roue
|
|
|
+
|
|
|
+⚠️ **Attention** : Privilégier Stimulus/Vue pour les fonctionnalités custom. Utiliser Bootstrap JS uniquement pour ses composants natifs.
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Implémentation
|
|
|
+
|
|
|
+### Phase 1 : Préparation (Semaine 1-2)
|
|
|
+- [ ] Audit complet du code jQuery existant
|
|
|
+- [ ] Identification des composants à migrer en priorité
|
|
|
+- [ ] Configuration de l'environnement de développement (Vue/Stimulus)
|
|
|
+- [ ] Création de templates de base pour Vue et Stimulus
|
|
|
+
|
|
|
+### Phase 2 : Migration (Semaine 3-8)
|
|
|
+- [ ] Migration des composants simples vers Stimulus
|
|
|
+- [ ] Migration des composants complexes vers Vue.js
|
|
|
+- [ ] Remplacement des plugins jQuery par des équivalents modernes
|
|
|
+- [ ] Tests complets à chaque migration
|
|
|
+
|
|
|
+### Phase 3 : Nettoyage (Semaine 9-10)
|
|
|
+- [ ] Suppression de jQuery et ses dépendances
|
|
|
+- [ ] Suppression du code mort
|
|
|
+- [ ] Optimisation des bundles
|
|
|
+- [ ] Documentation finale
|
|
|
+
|
|
|
+### Phase 4 : Maintenance (Continu)
|
|
|
+- [ ] Formation de l'équipe sur les bonnes pratiques
|
|
|
+- [ ] Review systématique des PRs frontend
|
|
|
+- [ ] Mise à jour de la documentation
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Règles et bonnes pratiques
|
|
|
+
|
|
|
+### Pour Stimulus
|
|
|
+```javascript
|
|
|
+// Structure d'un contrôleur Stimulus
|
|
|
+import { Controller } from '@hotwired/stimulus';
|
|
|
+
|
|
|
+export default class extends Controller {
|
|
|
+ static targets = ['input', 'output'];
|
|
|
+ static values = { rate: Number };
|
|
|
+
|
|
|
+ connect() {
|
|
|
+ // Initialisation
|
|
|
+ }
|
|
|
+
|
|
|
+ update(event) {
|
|
|
+ // Logique métier
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### Pour Vue.js
|
|
|
+```javascript
|
|
|
+// Composant Vue.js (SFP)
|
|
|
+<template>
|
|
|
+ <div class="component">
|
|
|
+ <!-- Template -->
|
|
|
+ </div>
|
|
|
+</template>
|
|
|
+
|
|
|
+<script>
|
|
|
+export default {
|
|
|
+ props: [],
|
|
|
+ data() {
|
|
|
+ return {};
|
|
|
+ },
|
|
|
+ methods: {},
|
|
|
+};
|
|
|
+</script>
|
|
|
+
|
|
|
+<style scoped>
|
|
|
+/* Styles spécifiques au composant */
|
|
|
+</style>
|
|
|
+```
|
|
|
+
|
|
|
+### Architecture recommandée
|
|
|
+```
|
|
|
+assets/
|
|
|
+├── controllers/ # Controllers Stimulus
|
|
|
+│ ├── **/*.js
|
|
|
+│ └── index.js
|
|
|
+├── components/ # Composants Vue.js
|
|
|
+│ ├── **/*.vue
|
|
|
+│ └── index.js
|
|
|
+├── styles/
|
|
|
+│ └── **/*.scss
|
|
|
+└── app.js # Point d'entrée
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Critères de succès
|
|
|
+
|
|
|
+- [ ] 100% du code jQuery migré ou supprimé
|
|
|
+- [ ] Pas de nouvelles dépendances jQuery ajoutées
|
|
|
+- [ ] Tous les composants utilisent Vue.js ou Stimulus
|
|
|
+- [ ] Build Webpack sans erreurs
|
|
|
+- [ ] Tous les tests frontend passent
|
|
|
+- [ ] Performance améliorée (métriques à définir)
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Références
|
|
|
+
|
|
|
+- [Stimulus Handbook](https://stimulus.hotwired.dev/handbook)
|
|
|
+- [Vue.js Documentation](https://vuejs.org/guide/)
|
|
|
+- [Webpack Encore (Symfony)](https://symfony.com/doc/current/frontend.html)
|
|
|
+- [ADR Template](https://adr.github.io/)
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Historique
|
|
|
+
|
|
|
+| Date | Version | Changements | Auteur |
|
|
|
+|------|---------|-------------|--------|
|
|
|
+| 2024-11-08 | 1.0 | Création initiale | François |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+*Format inspiré de [MADR](https://adr.github.io/madr/)*
|
