Node.js : premiers pas

Premiers usages de Node.js : scripts, modules, fichiers, serveur HTTP. Les exemples utilisent des noms génériques et fonctionnent avec Node.js 22 et 24 (versions LTS). Node.js n’est pas encore installé ? Voir Installation.

Exécuter du JavaScript

node                                   # console interactive (Ctrl+d pour quitter)
node -e "console.log(1 + 2)"           # une expression
node script.js                         # un fichier
node --watch script.js                 # relance automatiquement à chaque modification

Premier script, bonjour.js :

const nom = process.argv[2] ?? 'monde';
console.log(`Bonjour, ${nom} !`);

node bonjour.js Alice          # Bonjour, Alice !

process.argv contient le chemin de Node, celui du script, puis les arguments.

Modules : ES modules ou CommonJS

Deux systèmes coexistent. Pour un nouveau projet, les modules ES sont recommandés : ajouter "type": "module" dans package.json.

// ES modules (import / export)
import { readFile } from 'node:fs/promises';
export function additionner(a, b) {
  return a + b;
}

// CommonJS (require / module.exports), forme historique
const { readFile } = require('node:fs/promises');
module.exports = { additionner };

Extension	Système utilisé
`.mjs`	Toujours ES modules
`.cjs`	Toujours CommonJS
`.js`	Selon `"type"` dans le `package.json` le plus proche (CommonJS par défaut)

Le préfixe node: (node:fs, node:path) désigne les modules intégrés de Node.js.

Variables d’environnement

const port = Number(process.env.PORT ?? 3000);
const mode = process.env.NODE_ENV ?? 'development';

PORT=8080 node serveur.js                  # définie pour une seule exécution

Charger un fichier .env sans dépendance :

PORT=8080
NODE_ENV=development

node --env-file=.env serveur.js

Lire et écrire des fichiers

import { readFile, writeFile, readdir, mkdir } from 'node:fs/promises';

const contenu = await readFile('donnees.json', 'utf8');
const donnees = JSON.parse(contenu);

donnees.visites = (donnees.visites ?? 0) + 1;
await writeFile('donnees.json', JSON.stringify(donnees, null, 2));

await mkdir('sortie', { recursive: true });
const fichiers = await readdir('.');
console.log(fichiers);

Les fonctions de node:fs/promises renvoient des promesses et s’utilisent avec await. L’await au niveau supérieur fonctionne dans les modules ES.

Un serveur HTTP minimal

import { createServer } from 'node:http';

const port = Number(process.env.PORT ?? 3000);

const serveur = createServer((requete, reponse) => {
  if (requete.url === '/sante') {
    reponse.writeHead(200, { 'Content-Type': 'application/json' });
    reponse.end(JSON.stringify({ statut: 'ok' }));
    return;
  }
  reponse.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
  reponse.end('Bonjour depuis Node.js\n');
});

serveur.listen(port, '127.0.0.1', () => {
  console.log(`Serveur démarré sur http://127.0.0.1:${port}`);
});

node serveur.js
curl http://127.0.0.1:3000/sante

Écouter sur 127.0.0.1 limite l’accès à la machine locale : en production, un reverse proxy (Caddy) expose le service (voir Mise en production).

Requêtes HTTP : `fetch`

fetch est intégré (aucun paquet à installer) :

const reponse = await fetch('https://api.exemple.com/etat');
if (!reponse.ok) throw new Error(`Erreur HTTP ${reponse.status}`);
const donnees = await reponse.json();
console.log(donnees);

Gérer les erreurs et l’arrêt propre

process.on('SIGTERM', () => {
  console.log('Arrêt demandé');
  serveur.close(() => process.exit(0));
});

process.on('unhandledRejection', (erreur) => {
  console.error('Promesse rejetée non gérée :', erreur);
  process.exit(1);
});

SIGTERM est le signal envoyé par systemd pour arrêter un service.

Tests intégrés

Node.js inclut un lanceur de tests :

import { test } from 'node:test';
import assert from 'node:assert/strict';

test('addition', () => {
  assert.equal(1 + 2, 3);
});

node --test                 # exécute les fichiers *.test.js

Structure d’un projet

monprojet/
├── package.json        # description et dépendances (voir la page npm)
├── package-lock.json   # versions exactes (à versionner)
├── .nvmrc              # version de Node.js (facultatif)
├── .gitignore          # node_modules, .env
├── src/
│   └── serveur.js
└── node_modules/       # dépendances installées (ne pas versionner)

Pour aller plus loin

Documentation officielle : nodejs.org/docs
Suite : npm : commandes essentielles