Fanspicy : Qu’est-ce que le fichier .nvmrc et comment l’utiliser

Quel est le fichier .nvmrc ?

Le dossier .nvmrc est un petit fichier texte placé à la racine d’un projet Node.js.
Il ne contient qu’une seule information : la version de Node que le projet recommande d’utiliser.
Grâce à cet indicateur, les développeurs travaillant dans un même référentiel peuvent facilement synchroniser leurs environnements, évitant ainsi les incompatibilités liées aux versions très anciennes ou très récentes de Node.

En pratique, .nvmrc agit comme un contrat implicite : chaque fois que vous ou un collaborateur ouvrez le projet, vous êtes invité à installer ou à basculer vers la version déclarée. Cela simplifie la gestion des dépendances, réduit les bugs liés aux changements de version et rend le processus d’intégration plus fluide.

---

Pourquoi le fichier .nvmrc est essentiel dans un flux de travail moderne

Cohérence entre les environnements de développement

• Évitez les «fonctionne sur ma machine»» : Lors de la correction de la version Node, tous les contributeurs exécutent le même runtime.
• Évitez les pauses de compilation : Certaines fonctionnalités (par exemple les modules ES, les API natives) sont introduites ou obsolètes d’une version à l’autre. Une version qui fonctionne sur le nœud 14 peut planter sur le nœud 18 si elle n’est pas contrôlée en version.

Gagnez du temps pour l’intégration

Un nouveau développeur n’a plus besoin de deviner quelle version installer ; il suffit de lire le fichier .nvmrc et exécutez une commande simple. Cela réduit les allers-retours avec le chef de projet et accélère l’intégration.

Prise en charge des environnements CI/CD

Les pipelines d’intégration continue (GitHub Actions, GitLab CI, CircleCI, etc.) peuvent lire .nvmrc pour choisir automatiquement la bonne version de Node, garantissant que les tests sont exécutés dans les mêmes conditions que le développement local.

---

Comment créer et configurer un fichier .nvmrc

Étape 1: Choisissez la version cible

Déterminez quelle version de Node répond aux besoins de votre application.

• Si vous utilisez des fonctionnalités spécifiques d’une version majeure, notez-le (par ex. 14.21.3).
• Si vous suivez LTS, indiquez simplement la version majeure (ex. 18).

Étape 2: Créer le fichier

A la racine du projet :

echo "18" > .nvmrc        # version majeure
# ou
echo "18.17.0" > .nvmrc   # version exacte

Le fichier ne doit avoir aucune extension et ne contenir aucune autre ligne.

Étape 3: Téléchargez le fichier

git add .nvmrc
git commit -m "Add .nvmrc to enforce Node version 18"
git push

De cette façon, chaque clone du référentiel aura le même fichier.

---

Pour utiliser .nvmrc avec NVM (gestionnaire de version de nœud)

Installation de NVM (rappel rapide)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# puis, dans le même terminal
source ~/.bashrc   # ou ~/.zshrc selon le shell

Changement automatique vers la version déclarée

1. Lire la version :

nvm use

nvm use lit automatiquement le fichier .nvmrc présent dans le répertoire courant (ou ses parents) et charge la version correspondante.

1. Installez la version si elle n’existe pas:

nvm install

Cette commande lit .nvmrc téléchargez la version manquante et utilisez-la.

Astuce: ajoutez un alias à votre ~/.bashrc ou ~/.zshrc pour automatiser le processus à chaque foiscd:

autoload -U add-zsh-hook
load-nvmrc() {
  if nvm -v &>/dev/null; then
    local node_version=$(nvm version "$(cat .nvmrc 2>/dev/null)" 2>/dev/null)
    if [ "$node_version" = "N/A" ]; then
      nvm install
    else
      nvm use
    fi
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc

Ainsi, chaque fois que vous changez de répertoire, NVM ajuste automatiquement la version.

---

Intégrer .nvmrc dans les scripts de projet

Exemple avec package.json

{
  "scripts": {
    "preinstall": "nvm install && nvm use",
    "start": "node index.js",
    "test": "npm run lint && jest"
  }
}

Le scénario preinstall garantit que la version correcte de Node est activée avant que les dépendances ne soient installées.

Utilisation dans les workflows GitHub Actions

name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc   # lit .nvmrc automatiquement
      - run: npm ci
      - run: npm test

Le terrain node-version-file lire directement .nvmrc en alignant le couloir avec la version souhaitée.

---

Bonnes pratiques et pièges à éviter

Meilleures pratiques	Risques / Pièges
Toujours version le dossier .nvmrc avec le code source.	Oublier de confirmer les résultats dans des environnements désynchronisés.
Utiliser la version principale de LTS (ex. 20) pour de nouveaux projets.	Choisir une version trop récente peut entraîner des incompatibilités avec des dépendances non mises à jour.
Pour mettre à jour .nvmrc dès que vous migrez vers une version supérieure de Node.	Le maintien d’une version obsolète bloque les améliorations de performances et les correctifs de sécurité.
Document dans le README la présence de .nvmrc et la commande à exécuter (nvm use).	Les nouveaux contributeurs peuvent ignorer le fichier et rencontrer de mystérieuses erreurs.
Associer avec engine Dans package.json : "node": ">=18 <20" pour faire respecter la restriction.	Reste seulement dans .nvmrc ce n’est pas suffisant si le projet est publié sur npm et utilisé sans NVM.

---

Cas d’utilisation typique: passage du nœud 14 au nœud 18 dans un projet existant

1. Vérifier la compatibilité dépendances (npm outdated, npm audit).
2. Mettre à jour le fichier :

echo "18" > .nvmrc
git add .nvmrc
git commit -m "Upgrade Node version to 18 (LTS)"

1. Installez la nouvelle version localement:

nvm install          # télécharge Node 18
nvm use              # bascule dessus
npm rebuild          # recompile les modules natifs
npm test             # s’assurer que la suite passe

1. Mettre à jour le flux de travail CI pour lire la nouvelle version (si vous utilisez setup-nodeil n’y a rien à changer).

Cette séquence minimise les perturbations et garantit que chaque développeur travaille sur la même base.

---

Résumé : pourquoi adopter .nvmrc tout de suite

• Uniformité: chaque machine utilise la même version de Node.
• Simplicité: une seule ligne de texte, sans configuration complexe.
• Automation: Les scripts NVM, les CI et les Dockerfiles peuvent être basés sur celui-ci.
• Sécurité: Vous vous assurez que les correctifs LTS sont appliqués dès que vous mettez à jour le fichier.

Lors de l’intégration .nvmrcà votre flux de travail, vous offrez à votre équipe un environnement de travail plus prévisible, réduisez les sources d’erreur liées aux versions et facilitez le déploiement continu.

Vous décidez: créez le fichier aujourd’hui .nvmrcà la racine de votre projet, choisissez la version LTS qui répond à vos besoins et voyez la différence !