Mettre en place un labo Node.js local avec des exemples concrets : guide pratique pas à pas

Intro

Un labo Node.js local est un espace de travail sécurisé sur votre machine pour tester, dépanner et apprendre de manière itérative, sans toucher à la production ni aux environnements d’équipe. En figeant les versions, en isolant les changements et en ajoutant des vérifications observables, vous rendez les résultats reproductibles et les problèmes faciles à diagnostiquer.

Dans ce guide, vous allez :

• Établir un environnement Node.js propre et versionné avec un gestionnaire de versions.
• Créer un répertoire de labo dédié contenant trois petits projets autonomes.
• Exécuter et valider chaque projet avec des commandes concrètes.
• Diagnostiquer les problèmes courants et revenir en sécurité à un état connu et valide.
• Adopter un court runbook quotidien pour des sessions rapides et prévisibles.

Pourquoi c’est important :

• Une configuration locale claire réduit le rework en séparant l’apprentissage des décisions de déploiement et en vous aidant à itérer sans effets de bord.
• Votre premier pilote doit être étroit et mesurable afin d’observer le comportement en local avant toute adoption plus large.

Inventaire des versions et de l’environnement

Avant d’installer quoi que ce soit, capturez votre état actuel. Cette base vous aide à reproduire les résultats et sera votre premier point de revue en cas de comportement inattendu.

Relevez votre OS et votre architecture :

• macOS : sw_vers && uname -m
• Linux : lsb_release -a 2>/dev/null || cat /etc/os-release; uname -m
• Windows (PowerShell) : Get-ComputerInfo | Select-Object OsName, OsVersion, OsArchitecture

Relevez Node.js et npm si présents :

• node -v || echo 'node not installed'
• npm -v || echo 'npm not installed'

Relevez votre shell et le chemin de Node (si présent) :

• Shell Unix : echo $SHELL && which node || command -v node
• Windows PowerShell : $PSVersionTable.PSVersion; Get-Command node -ErrorAction SilentlyContinue

Choisissez la racine de votre labo et des ports par défaut :

• Racine de labo (Unix) suggérée : ~/lab/node
• Racine de labo (Windows) suggérée : C:\lab\node
• Ports suggérés : 3000 et 3001 pour des APIs HTTP

Exemples de valeurs d’inventaire (à titre illustratif) :

• OS et arch : macOS 13.6 sur arm64
• Node.js : v18.19.1
• npm : 9.6.7
• Shell : /bin/zsh
• Chemin de Node : /Users/alex/.nvm/versions/node/v18.19.1/bin/node
• Racine du labo : /Users/alex/lab/node
• Ports : 3000, 3001

Parcours de configuration sécurisé

Faites des choix d’implémentation qui gardent le labo prévisible et à faible risque.

Principes :

• Utilisez Node.js LTS. Privilégiez la stabilité au cutting edge.
• Gérez les versions par utilisateur avec nvm (Unix) ou nvm-windows (Windows). Ne dépendez pas du Node système.
• Utilisez npm (fourni avec Node) pour éviter des pièces mobiles supplémentaires.
• Travaillez dans un répertoire de labo dédié pour prévenir la contamination entre projets.
• Évitez sudo ou Administrateur pour installer les dépendances de projet.

Étapes :

1. Installer un gestionnaire de versions Node.js

• macOS/Linux (lisez le script en local avant exécution) :

# installer nvm (lisez le script avant d'exécuter)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# recharger le shell (au choix)
. "$HOME/.nvm/nvm.sh" || source "$HOME/.bashrc" || source "$HOME/.zshrc"
# vérifier
command -v nvm && nvm --version

• Windows : installez nvm-windows via son installeur. Après l’installation, ouvrez un nouveau PowerShell et exécutez :

nvm version

1. Installer Node.js LTS et le définir par défaut

• macOS/Linux :

nvm install --lts
nvm use --default 'lts/*'
node -v
npm -v

• Windows PowerShell :

nvm list available  # voir les LTS disponibles
nvm install lts     # ou spécifiez une version, ex. nvm install 18.19.1
nvm use lts
node -v
npm -v

1. Créer une racine de labo propre

• macOS/Linux :

mkdir -p ~/lab/node && cd ~/lab/node
pwd

• Windows PowerShell :

New-Item -Type Directory -Path C:\lab\node -Force | Out-Null
Set-Location C:\lab\node
Get-Location

1. Choisir des ports de base et vérifier leur disponibilité

• Unix :

lsof -i :3000 || echo 'port 3000 free'

• Windows :

netstat -ano | findstr :3000

Exemples pratiques

Vous allez créer trois petits projets. Chacun vit dans son propre dossier sous la racine du labo et s’exécute de façon indépendante.

1) 01-hello-http (aucune dépendance externe)

Créer le projet :

mkdir 01-hello-http && cd 01-hello-http
npm init -y
npm pkg set scripts.start='node index.js'

Créer index.js :

// index.js
const http = require('http');
const PORT = process.env.PORT || 3000;

const server = http.createServer((req, res) => {
  const ts = new Date().toISOString();
  console.log(`${ts} ${req.method} ${req.url}`);
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ ok: true, message: 'hello-http', time: Date.now() }));
});

server.listen(PORT, () => {
  console.log(`hello-http listening on http://localhost:${PORT}`);
});

Lancer :

npm start

Tester dans un autre terminal :

curl -s http://localhost:3000 | jq .

Réponse attendue (exemple) :

{
  "ok": true,
  "message": "hello-http",
  "time": 1699999999999
}

2) 02-express-api (routage minimal)

Créer le projet :

cd ..
mkdir 02-express-api && cd 02-express-api
npm init -y
npm install express
npm pkg set scripts.start='node server.js'

Créer server.js :

// server.js
const express = require('express');
const app = express();
const PORT = process.env.PORT || 3001;

app.use(express.json());
app.get('/health', (req, res) => res.json({ status: 'ok', at: Date.now() }));
app.get('/add', (req, res) => {
  const a = Number(req.query.a || 0);
  const b = Number(req.query.b || 0);
  res.json({ a, b, sum: a + b });
});

app.listen(PORT, () => {
  console.log(`express-api listening on http://localhost:${PORT}`);
});

Exécuter et tester :

npm start
# nouveau terminal
curl -s http://localhost:3001/health
curl -s "http://localhost:3001/add?a=2&b=5"

Réponses attendues (exemples) :

{"status":"ok","at":1699999999999}
{"a":2,"b":5,"sum":7}

3) 03-file-io-and-env (fs + dotenv)

Créer le projet :

cd ..
mkdir 03-file-io-and-env && cd 03-file-io-and-env
npm init -y
npm install dotenv
npm pkg set scripts.start='node app.js'

Ajouter .env et un fichier de données d’exemple :

# .env (exemple)
APP_NAME=lab-fs
DATA_FILE=data.json

# data.json (exemple)
{
  "items": [1, 2, 3, 4]
}

Créer app.js :

// app.js
require('dotenv').config();
const fs = require('fs');
const path = require('path');

const appName = process.env.APP_NAME || 'lab-fs';
const dataFile = process.env.data_FILE || process.env.DATA_FILE || 'data.json';

const p = path.resolve(__dirname, dataFile);
if (!fs.existsSync(p)) {
  console.error(`missing data file: ${p}`);
  process.exit(1);
}

const raw = fs.readFileSync(p, 'utf8');
const parsed = JSON.parse(raw);
const items = Array.isArray(parsed.items) ? parsed.items : [];
const sum = items.reduce((a, b) => a + b, 0);

console.log(JSON.stringify({ appName, file: p, count: items.length, sum }));

Lancer et tester :

npm start

Sortie attendue (exemple) :

{"appName":"lab-fs","file":"/path/03-file-io-and-env/data.json","count":4,"sum":10}

Astuce : ajoutez .env à .gitignore dans ce projet pour éviter de commettre des secrets.

Vérification et diagnostic

La vérification prouve que votre labo se comporte comme prévu. Le diagnostic vous aide à trouver pourquoi il ne le fait pas.

Vérifiez que les versions sont celles attendues :

node -v
npm -v

Vérifiez que les écouteurs sont actifs :

• Pour 01-hello-http sur le port 3000 (Unix) :

lsof -i :3000 | grep LISTEN || echo 'no listener on 3000'

• Pour 02-express-api sur le port 3001 (Unix) :

lsof -i :3001 | grep LISTEN || echo 'no listener on 3001'

• Alternative Windows :

netstat -ano | findstr LISTENING | findstr :3000
netstat -ano | findstr LISTENING | findstr :3001

Vérifiez que les endpoints renvoient les charges utiles attendues :

curl -s http://localhost:3000 | jq .
curl -s http://localhost:3001/health | jq .
curl -s "http://localhost:3001/add?a=10&b=15" | jq .

Activez un débogage de base si nécessaire :

• Utilisez l’inspecteur Node : node --inspect index.js (ou fichier d’entrée), puis ouvrez chrome://inspect et attachez-vous au processus.
• Ajoutez des logs ciblés autour des zones suspectes plutôt qu’un logging verbeux global.

Tests de fumée rapides avec le runner de test intégré de Node (optionnel) :

# dans 01-hello-http
mkdir -p test
cat > test/smoke.test.js <<'EOF'
const test = require('node:test');
const assert = require('node:assert');

test('math still works', () => {
  assert.strictEqual(2 + 3, 5);
});
EOF
node --test

Pannes courantes et récupération

Problèmes fréquents et correctifs pratiques :

• Symptôme : EADDRINUSE sur le port 3000
• Cause probable : un autre processus utilise le port
• Correctif (Unix) : lsof -i :3000 -sTCP:LISTEN -t | xargs kill -9 ou changez la variable d’environnement PORT
• Correctif (Windows) : netstat -ano | findstr :3000 puis taskkill /PID <pid> /F

• Symptôme : MODULE_NOT_FOUND
• Cause probable : dépendance non installée ou chemin d’import incorrect
• Correctif : exécutez npm install dans le dossier du projet; vérifiez require('./file') vs require('module')

• Symptôme : SyntaxError concernant import/export
• Cause probable : décalage entre ESM et CommonJS
• Correctif : utilisez CommonJS require dans ces exemples, ou passez à ESM en ajoutant "type": "module" et en utilisant import de façon cohérente

• Symptôme : Permission denied lors de l’installation
• Cause probable : installation globale ou dans un chemin protégé
• Correctif : installez par projet sans sudo/Administrateur. Assurez-vous que la racine du labo est dans votre home utilisateur

• Symptôme : Comportement Node inattendu
• Cause probable : mauvaise version de Node active
• Correctif : nvm use 'lts/*' puis vérifiez avec node -v. Optionnellement, épinglez engines dans package.json

• Symptôme : L’app lit la mauvaise configuration
• Cause probable : variables d’environnement non chargées
• Correctif : vérifiez l’emplacement de .env; assurez-vous que require('dotenv').config() s’exécute avant de lire process.env

• Symptôme : Dépendances obsolètes ou cassées
• Cause probable : node_modules ou cache corrompus
• Correctif : rm -rf node_modules package-lock.json && npm cache verify && npm ci

Procédures de retour arrière et de récupération :

• Changer de version Node en sécurité :

nvm ls
nvm use 'lts/*'
nvm alias default 'lts/*'

• Restaurer un projet à un état propre :

# depuis le dossier du projet
rm -rf node_modules package-lock.json
npm ci  # installation propre depuis le lockfile

• Revenir en arrière sans contrôle de version :

# gardez une copie d'un projet fonctionnel en sauvegarde
cp -a 01-hello-http 01-hello-http.bak
# si le projet casse, supprimez et restaurez depuis la sauvegarde
rm -rf 01-hello-http && cp -a 01-hello-http.bak 01-hello-http

• Libérer un port bloqué lorsque le processus est inconnu :

# Unix
lsof -i :3000 -sTCP:LISTEN -t | xargs -r kill -9 || echo 'no listener on 3000'

# Windows
for /f "tokens=5" %a in ('netstat -ano ^| findstr :3000 ^| findstr LISTENING') do taskkill /PID %a /F

• Valider la récupération :

• Réexécutez node -v pour confirmer la version.
• Lancez npm start et interrogez l’endpoint avec curl.
• Confirmez la présence d’un écouteur avec lsof ou netstat.

Liste d’opérations

Utilisez ce court runbook pour garder vos sessions rapides et prévisibles.

Pré-vol (1 minute) :

• nvm use 'lts/*' && node -v && npm -v
• Confirmez la racine du labo : pwd (ou Get-Location) doit afficher votre répertoire de labo.
• Vérifiez que les ports 3000 et 3001 sont libres.

Étapes de session :

• Choisissez un dossier de projet (01-hello-http, 02-express-api ou 03-file-io-and-env).
• Exécutez npm ci si vous avez modifié des dépendances; sinon npm install une seule fois par nouveau clone.
• Démarrez l’app : npm start.
• Vérifiez avec curl et confirmez que les logs affichent les lignes attendues.

Diagnostic (si nécessaire) :

• Activez l’inspecteur : node --inspect index.js ou fichier d’entrée équivalent.
• Vérifiez les écouteurs : lsof -i :PORT (Unix) ou netstat sous Windows.
• Lisez les 20 dernières lignes de logs et isolez le chemin fautif.

Nettoyage :

• Arrêtez le processus avec Ctrl+C.
• Libérez les ports si des processus persistent.
• Commitez ou copiez des instantanés fonctionnels pour un retour arrière facile la prochaine fois (optionnel).

Conclusion

Vous avez maintenant un labo Node.js local sûr et reproductible : versions figées via nvm, arborescence propre et trois projets pratiques couvrant HTTP de base, routage minimal et E/S fichiers avec variables d’environnement. Vous pouvez vérifier le comportement avec des commandes simples, diagnostiquer rapidement les problèmes courants et revenir en quelques minutes à un état connu et fiable.

Prochaines étapes :

• Gardez le pilote étroit et mesurable : étendez un exemple à la fois et ajoutez un test simple par projet.
• Créez un nouveau dossier de projet lorsque vous explorez une préoccupation distincte (par exemple, un client de cache ou une bibliothèque de validation) pour que les expériences restent isolées.
• Capturez les versions et résultats de chaque session dans un fichier NOTES.md au niveau du projet afin de faciliter la reproduction ultérieure.