Les deux systèmes existent pour des raisons historiques, et le choix pour un nouveau projet penche vers ESM (le standard), mais CommonJS reste incontournable à connaître — clarifions cette coexistence qui déroute beaucoup de débutants. Pourquoi DEUX systèmes ? C'est une question d'histoire. Quand Node est né (2009), JavaScript n'avait PAS de système de modules officiel (le langage n'en prévoyait pas). Node a donc créé le sien : CommonJS (require/module.exports), qui est devenu le standard de facto de tout l'écosystème Node — des millions de paquets npm l'utilisent. Des années plus tard (ES6/2015), le langage JavaScript a enfin standardisé SON propre système de modules : les ES Modules (import/export), utilisés dans les navigateurs modernes. Node a progressivement adopté ce standard officiel, tout en gardant le support de CommonJS (pour ne pas casser l'écosystème existant). D'où la coexistence : CommonJS (l'historique de Node, omniprésent) et ES Modules (le standard officiel du langage, l'avenir). Le choix pour un NOUVEAU projet : (1) ES Modules est recommandé, car : c'est le STANDARD officiel du langage (pas une invention spécifique à Node) ; c'est cohérent avec le front-end (même syntaxe import/export dans le navigateur, React, etc. — un seul système à connaître pour full-stack) ; c'est la direction d'AVENIR (l'écosystème migre progressivement vers ESM) ; la syntaxe est plus moderne et standardisée. (2) Mais CommonJS reste un choix valable, notamment si : vous travaillez avec beaucoup de code/paquets anciens ; vous préférez sa simplicité (chargement synchrone, moins de subtilités) ; votre équipe/projet existant l'utilise déjà (cohérence). Pour APPRENDRE, il faut connaître les DEUX : (1) vous LIREZ énormément de CommonJS (l'immense majorité du code Node existant, tutoriels, paquets, exemples l'utilisent — require est partout) ; (2) vous verrez de plus en plus d'ESM (les nouveaux projets, les bibliothèques modernes) ; (3) vous devez donc comprendre require/module.exports ET import/export. La bonne nouvelle : le PRINCIPE est identique (exporter ce qu'un module rend disponible, importer ce dont on a besoin) ; seule la syntaxe diffère. Une fois le concept de module compris, passer de l'une à l'autre est simple. Les points de vigilance sur la coexistence : (1) Activation d'ESM : par défaut, Node traite les .js comme CommonJS. Pour ESM, il faut soit des fichiers .mjs, soit "type": "module" dans package.json (alors les .js sont ESM, et pour du CommonJS ponctuel on utilise .cjs). (2) Mélange : on peut importer du CommonJS depuis de l'ESM (courant, car beaucoup de paquets sont en CJS), mais l'inverse (require d'un module ESM) est plus délicat. (3) Différences techniques : ESM charge de façon asynchrone, exige les extensions de fichier explicites dans les imports locaux (./x.js pas ./x), est en mode strict, et n'a pas __dirname/require nativement (des équivalents existent). (4) Cohérence : dans UN projet, tenez-vous à un système (tout ESM ou tout CJS) autant que possible, pour éviter les frictions. Recommandation pratique : (1) pour un nouveau projet d'apprentissage, ESM (le standard, l'avenir, cohérent avec le front) est un bon choix — activez "type": "module" ; (2) MAIS soyez à l'aise avec CommonJS car vous le rencontrerez constamment (paquets, exemples, code existant) ; (3) concentrez-vous sur le PRINCIPE (organiser en modules) qui transcende la syntaxe. Ne vous bloquez pas sur ce choix : les deux fonctionnent, se ressemblent conceptuellement, et l'important est de savoir découper votre code en modules propres — la compétence réelle, au-delà de require vs import.

Bien organiser son code en modules est une compétence d'architecture qui distingue un script bricolé d'une application maintenable — et elle repose sur des principes indépendants de la syntaxe (require ou import). Voici comment structurer proprement. Le principe fondamental : chaque module a UNE responsabilité claire. Un module ne doit pas être un fourre-tout, mais avoir un rôle précis : gérer les utilisateurs, formuler les requêtes de base de données, définir les routes, contenir des utilitaires de validation, etc. Cette « séparation des responsabilités » rend le code compréhensible (on sait où trouver quoi), réutilisable (un module bien découpé se réutilise) et maintenable (on modifie un module sans casser les autres). Les bonnes pratiques d'organisation : (1) Découpez par fonctionnalité/responsabilité, pas au hasard. Regroupez ce qui va ensemble (toute la logique utilisateur dans un module/dossier user), séparez ce qui est distinct. Une structure typique d'application (qu'on approfondira avec le MVC, section 4-1) sépare : les routes (les URL), les contrôleurs (la logique de traitement), les modèles (les données), les services (la logique métier), les utilitaires. (2) Exportez une interface claire : un module exporte ce que les autres doivent utiliser (ses fonctions/objets publics), et garde le reste privé (interne au module). N'exportez que ce qui est nécessaire — un module avec une interface claire et minimale est plus facile à utiliser et à faire évoluer. (3) Nommez clairement : le nom d'un fichier/module doit dire ce qu'il fait (userService.js, validation.js, db.js). Un nommage clair est une documentation gratuite. (4) Évitez les dépendances circulaires : un module A qui importe B qui importe A crée des problèmes (comme en conception logicielle générale). Organisez les dépendances de façon hiérarchique (les modules de bas niveau — utilitaires, config — sont importés par les modules de haut niveau, pas l'inverse). (5) Un dossier par domaine sur les gros projets : regroupez les modules liés dans des dossiers (un dossier users/ avec ses routes, contrôleur, modèle) pour une organisation lisible à grande échelle. (6) Gérez la configuration séparément : centralisez la config (variables d'environnement, constantes) dans des modules dédiés, importés là où nécessaire (plutôt que des valeurs éparpillées). (7) Modules « minces » et cohérents : évitez les modules géants (difficiles à comprendre) et les modules trop petits/fragmentés (dépendances éparpillées) — trouvez le bon grain (un module = une responsabilité cohérente, de taille raisonnable). Les bénéfices d'une bonne modularité : (1) Compréhension : on navigue et on comprend le code facilement (chaque module a un rôle clair). (2) Réutilisation : un module bien conçu se réutilise dans le projet ou ailleurs. (3) Maintenance : on modifie/corrige un module sans effet de bord sur le reste (couplage faible). (4) Collaboration : plusieurs personnes travaillent sur des modules différents sans se marcher dessus. (5) Testabilité : un module isolé, avec une interface claire, se teste facilement (section 4-4). Les erreurs à éviter : (1) le « God module » (un fichier géant qui fait tout) ; (2) les responsabilités mélangées (un module qui gère à la fois les routes, la base et la validation) ; (3) les dépendances désordonnées (tout importe tout) ; (4) les exports excessifs (exposer des détails internes qui devraient rester privés). Une image : organiser son code en modules, c'est comme ranger une maison — chaque chose à sa place, dans la bonne pièce, facile à retrouver. Un code modulaire bien pensé est agréable à faire évoluer ; un code monolithique et désordonné devient vite un cauchemar. Cette compétence (penser en responsabilités, découper proprement, gérer les dépendances) est fondamentale et transversale (elle vaut au-delà de Node) — investissez-y de l'attention dès vos premiers projets. La syntaxe (require/import) est le « comment » ; l'organisation (quelles responsabilités, quels modules, quelles dépendances) est le « quoi » et le « pourquoi », bien plus important. Un bon développeur pense d'abord à la structure, ensuite à la syntaxe.