## 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 :

- 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 

- 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 

- 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 

- 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 /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.