0001-unification-frontend-vuejs-stimulus.md 7.0 KB
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
// 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
// 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
Historique
| Date | Version | Changements | Auteur |
|---|---|---|---|
| 2024-11-08 | 1.0 | Création initiale | François |
Format inspiré de MADR