Guide pour Configurer une Version Indépendante de Node.js par Projet avec ServBay (macOS)

ServBay est un environnement de développement web local puissant, pensé pour les développeurs et offrant une solution tout-en-un. Il intègre de multiples langages de programmation, bases de données et serveurs web, dont Node.js. L’un de ses atouts majeurs réside dans sa gestion native flexible des multiples versions de Node.js. Grâce à un simple fichier de configuration, vous pouvez facilement définir la version de Node.js requise pour chaque projet, sans dépendre de gestionnaires de versions externes comme NVM ou fnm, ni de conteneurs Docker, simplifiant ainsi vos flux de travail et évitant les conflits de versions ainsi que la pollution globale de l’environnement système.

Ce guide présente en détail comment utiliser le fichier .servbay.config de ServBay pour contrôler la version de Node.js au niveau du projet.

Pourquoi choisir .servbay.config de ServBay pour gérer les versions de Node.js ?

Les méthodes classiques de gestion des versions de Node.js, telles que l’utilisation de NVM ou une installation manuelle, peuvent présenter plusieurs inconvénients :

• Pollution et conflits globaux : Installer Node.js globalement ou changer la version globale via un gestionnaire peut entraîner des conflits de dépendances entre vos différents projets.
• Temps d’installation et de compilation : Installer une nouvelle version ou passer d’une architecture à l’autre (comme x86_64 à arm64) peut exiger la recompilation de modules, opérations longues ou fastidieuses.
• Surcharge des conteneurs Docker : Si vous avez juste besoin d’une version spécifique de Node.js, l’utilisation d’un conteneur Docker complet peut être excessivement lourde.

ServBay préinstalle de nombreuses versions majeures et mineures populaires de Node.js (il prend actuellement en charge v12 à v23, consultables et gérables depuis la rubrique “Packages” de l’application ServBay), et, associé au fichier .servbay.config, offre une solution bien plus élégante :

• Changement instantané : Les versions sont déjà installées, le basculement est donc quasi immédiat.
• Isolation par projet : Les configurations ne s’appliquent qu’au répertoire du projet, garantissant une isolation des versions à l’échelle du projet.
• Aucune pollution globale : Aucun changement n’est apporté à l’environnement système, qui reste propre.
• Intégration profonde avec ServBay : Tout cela s’intègre parfaitement à l’environnement de développement ServBay, en synergie avec les autres paquets gérés (PHP, bases de données, serveurs web, etc.).

Prérequis

Avant de commencer, assurez-vous que :

1. ServBay est correctement installé et lancé sur votre macOS.
2. Dans l’application ServBay, depuis la section “Packages”, la ou les versions de Node.js requises pour votre projet sont bien installées et activées.
3. Vous disposez d’un répertoire projet nécessitant une configuration Node.js spécifique.

Principe fondamental

Lorsque vous travaillez dans le terminal intégré de ServBay, celui-ci surveille le dossier actuel. À chaque fois que vous utilisez la commande cd pour entrer dans un dossier, ServBay recherche, dans ce dossier et ses répertoires parents, un fichier nommé .servbay.config. Dès que ce fichier est trouvé (le plus proche du répertoire courant étant prioritaire), ServBay lit sa configuration et ajuste dynamiquement les variables d’environnement de la session terminal selon ces paramètres, par exemple en modifiant le PATH pour pointer vers la version Node.js déclarée dans .servbay.config.

Ce mécanisme garantit que chaque session terminal dans un projet distinct charge et utilise automatiquement la version de Node.js qui lui est propre, sans nécessiter de changement manuel de version.

Étapes de configuration

Configurer une version indépendante de Node.js par projet est très simple et ne prend que deux étapes :

Étape 1 : Créer et éditer le fichier .servbay.config

Dans le répertoire racine de votre projet (généralement là où se trouve votre package.json), créez un fichier nommé .servbay.config.

Ouvrez-le avec votre éditeur de texte favori et ajoutez les lignes suivantes :

# Spécifier la version majeure de Node.js à utiliser pour ce projet
# ServBay sélectionnera automatiquement la dernière version installée pour cette branche majeure
NODE_VERSION=20

# Optionnel : configurer le miroir npm ou pnpm pour accélérer l’installation des dépendances
# Si vous êtes en Chine continentale, il est recommandé d’utiliser un miroir local
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

# Optionnel : spécifier le répertoire de cache pour npm ou pnpm
# Nous conseillons d’utiliser le répertoire temporaire de ServBay pour éviter de polluer votre système ou votre dossier utilisateur
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

Explications des paramètres de configuration :

• NODE_VERSION : Obligatoire. Indique le numéro de version majeure de Node.js nécessaire au projet. Par exemple, 20 sélectionnera la version la plus récente 20.x.x parmi celles installées par ServBay. Veillez à ce que cette version soit bien installée.
• YARN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY : Optionnel. Sert à indiquer l’adresse du registre miroir pour Yarn ou npm, ce qui peut être très utile pour accélérer le téléchargement des dépendances, notamment en cas de connexion lente.
• NPM_CONFIG_CACHE : Optionnel. Sert à définir le dossier de cache pour npm ou pnpm. Mettre ce répertoire dans le dossier temporaire de ServBay (/Applications/ServBay/tmp/npm/cache) permet de centraliser la gestion du cache et d’éviter de le disperser sur le système.

Enregistrez et fermez le fichier .servbay.config.

Étape 2 : Vérification de la version dans le terminal ServBay

1. Ouvrez l’interface principale de l’application ServBay.

2. Cliquez sur le bouton “Terminal” pour lancer le terminal intégré de ServBay.

3. Dans le terminal, allez dans le dossier de votre projet avec la commande cd :

   cd /Applications/ServBay/www/nom-de-votre-projet

   (Remplacez /Applications/ServBay/www/nom-de-votre-projet par le chemin réel de votre projet.)

4. Lancez la commande node -v pour vérifier la version de Node.js effectivement utilisée.

   node -v

   Le résultat affiché devrait correspondre, par exemple, à la version v20.x.x spécifiée dans .servbay.config.

5. Vous pouvez aussi lancer npm -v (ou pnpm -v, yarn -v) pour vérifier que le gestionnaire de paquets utilisé correspond bien à la version Node.js active pour ce projet.

Désormais, toute commande Node.js, npm, pnpm ou yarn lancée dans ce dossier projet utilisera la version de Node.js et le gestionnaire associé définis dans .servbay.config.

Exemple d’utilisation

Voici un exemple simple illustrant comment .servbay.config permet de basculer automatiquement la version de Node.js entre différents projets.

Supposons que vous ayez deux projets : project-a nécessitant Node.js v18 et project-b nécessitant Node.js v20.

1. Créer les dossiers de projet et les fichiers de configuration :

   # Créer deux dossiers exemples dans le répertoire www de ServBay
   mkdir /Applications/ServBay/www/project-a
   mkdir /Applications/ServBay/www/project-b
   
   # Créer le .servbay.config pour project-a avec Node.js v18
   echo "NODE_VERSION=18" > /Applications/ServBay/www/project-a/.servbay.config
   
   # Créer le .servbay.config pour project-b avec Node.js v20
   echo "NODE_VERSION=20" > /Applications/ServBay/www/project-b/.servbay.config

2. Vérifier la bascule dans le terminal ServBay :

   Ouvrez le terminal ServBay, puis lancez les commandes suivantes :

   # Aller dans project-a
   cd /Applications/ServBay/www/project-a
   # Vérifier la version Node.js
   node -v
   # Attendu : v18.x.x
   
   # Aller dans project-b
   cd ../project-b
   # Vérifier la version Node.js
   node -v
   # Attendu : v20.x.x
   
   # Revenir à project-a
   cd ../project-a
   # Vérifier la version Node.js
   node -v
   # Attendu : v18.x.x

Ce simple exemple montre que ServBay applique automatiquement le paramètre NODE_VERSION de .servbay.config en fonction du dossier courant, assurant ainsi un changement transparent de version Node.js.

L’illustration ci-dessous montre le changement automatique de version Node.js selon le projet courant (l’apparence réelle de l’interface peut différer) :

Points d’attention

• Le fichier .servbay.config doit être placé dans le dossier du projet ou l’un de ses parents. ServBay remonte l’arborescence et utilisera le premier fichier .servbay.config trouvé (le plus proche).
• Assurez-vous de travailler dans le terminal intégré de ServBay ou dans un terminal externe ayant les variables d’environnement ServBay correctement configurées.
• La version renseignée via NODE_VERSION doit être installée et activée dans l’application ServBay. Sinon, ServBay utilisera la version par défaut ou sera incapable de trouver la commande Node.js.
• Les paramètres de .servbay.config n’impactent que la session terminal courante et ses sous-processus. Ils n’altèrent ni l’environnement système global ni les programmes lancés hors environnement ServBay.

FAQ — Foire aux questions

Q : Que se passe-t-il si mon dossier projet ne contient pas de fichier .servbay.config ?

R : Si ServBay ne trouve pas de fichier .servbay.config dans le dossier courant ni dans ses parents, il appliquera sa configuration globale ou utilisera la version Node.js par défaut (généralement celle marquée “Par défaut” dans ServBay).

Q : Comment savoir quelles versions de Node.js sont gérées par ServBay ?

R : Ouvrez ServBay et naviguez vers la section “Packages” via le menu latéral. Vous y retrouverez la liste de tous les paquets disponibles et installés, dont les différentes versions de Node.js, activables ou désactivables par simple coche.

Q : Les paramètres de .servbay.config affectent-ils tout mon système ?

R : Pas du tout. Les paramètres du fichier .servbay.config s’appliquent uniquement à la session de terminal ServBay active ou à tout processus utilisant les variables d’environnement ServBay. Ils ne modifient pas les variables d’environnement globales du système, ni n’affectent les programmes lancés hors de ServBay. C’est exactement ce qui garantit l’isolation projet par projet.

Q : Puis-je configurer d’autres paramètres liés à ServBay dans .servbay.config en dehors de NODE_VERSION ?

R : Absolument. Le fichier .servbay.config est conçu pour permettre la configuration de variables d’environnement au niveau du projet, au-delà des seuls paramètres Node.js. Tout paramètre compatible sera pris en compte pour les commandes exécutées dans ce projet, et la liste des options disponibles pourra évoluer au fil des versions de ServBay, mais la définition de variables d’environnement reste au cœur de ce mécanisme.

Conclusion

En exploitant le fichier .servbay.config de ServBay, vous pouvez facilement et efficacement assigner et gérer une version indépendante de Node.js pour chacun de vos projets locaux. Cette méthode, plus légère et pratique que les gestionnaires de versions traditionnels ou la virtualisation par conteneur, s’intègre parfaitement à l’environnement de développement de ServBay. Vous bénéficiez d’un workflow de développement plus stable et plus collaboratif. Adoptez dès aujourd’hui .servbay.config dans vos projets, et profitez de la simplicité apportée par ServBay !