Cartouche

Barême

Introduction

Lors de ce module, nous allons construire un projet d’API web en NodeJS. Le but de ce sujet va être de préparer le terrain en installant les outils et bibliothèques de base dont nous auront besoin.

On va s’intéresser à l’installation de :

• node le moteur qui va exécuter notre code ;
• pnpm un gestionnaire de projets JS et de dépendances NPM ;
• tsc le compilateur typescript, le langage dans lequel on va écrire notre code ;
• vitest un framework de tests unitaires ;
• biome un outil d’analyse statique (lint) et de formatage de code source.

Installation de NodeJS

Si vous êtes sur Linux, ou en WSL, vous pouvez installer nodejs depuis votre gestionnaire de paquet si tant est que vous avez accès à la verion LTS de NodeJS (au 25 août 2025 il s’agit de la v22.18).

Autrement rendez-vous sur cette page et sélectionnez :

• pour Linux : “Package Manager”, la version LTS et NVM (pensez à sourcer votre .bashrc après la première commande) ;
• pour MacOS, en fonction de ce que vous préférez :
  • “Package Manager”, la version LTS et NVM ou brew (si vous avez déjà brew d’installé),
  • “Prebuilt Installer”, la version LTS et l’architecture de votre processeur ;
• pour Windows en fonction de ce que vous préférez :
  • “Prebuilt Installer” et la version LTS,
  • “Package Manager”, la version LTS et chocolatey (si vous utilisez déjà chocolatey.

Vous pouvez lancer le REPL node et tester quelques lignes de codes :

$ node
Welcome to Node.js v22.18.0.
Type ".help" for more information.
> console.log("hello world this is me")
hello world this is me
undefined
> process.exit()

Création du dépôt avec pnpm

Alors déjà : c’est quoi pnpm ? C’est un gestionnaire de projet et de dépendances pour les projets JavaScript comme l’est npm. Les principales différences avec npm sont :

• la vitesse,
• le cache local de paquets,
• la portabilité (pnpm reproduit les mêmes installation sur Linux, Windows et MacOS, là ou npm n’y parvient pas.)

Si votre installation de NodeJS est bien faite, pour installer pnpm il suffit de faire :

corepack enable # linux: peut-être sudo ; windows: faites un terminal admin

Sans être super-utilisateur, dans un terminal, dans un dossier de projet vous pouvez :

corepack use pnpm

Petits changements

Dans package.json, ajoutez "type": "module" pour nous permettre d’utiliser le mot clé import dans nos fichiers sources.

Créez le fichier .editorconfig avec le contenu suivant :

[*]
# end_of_line = lf
insert_final_newline = true
indent_style = space
indent_size = 2

Il permet d’indiquer à vos éditeurs de code (parfois à l’aide d’un plugin, quels paramètre d’indentation utiliser.) Consultez https://editorconfig.org/ pour plus d’information.

Commit

À ce stade assurez-vous de faire un commit et de push sur la forge.

Meow

Essayons d’installer un paquet et de s’en servir depuis un fichier source.

Pour ajouter un paquet en dépendance de notre projet on fait :

pnpm add lolcatjs

Cela a pour effet de l’installer et de l’ajouter à package.json.

Si vous voulez des information sur un paquet vous pouvez faire une recherche sur le site de npm

Créez un fichier index.js avec le contenu suivant :

import * as lolcat from "lolcatjs"

lolcat.options.seed = Math.round(Math.random() * 1000)
lolcat.options.colors = true

lolcat.fromFile(process.argv[1])

Enfin exécutez le avec la commande :

node index.js

Vous devriez voir votre fichier source, multicolore, s’afficher sur la sortie standard. Si ça n’est pas le cas, essayez de comprendre l’erreur que vous avez, n’hésitez pas à demande de l’aide.

Ajoutez les fichiers qui ont changé index.js, package.json, pnpm-lock.yaml, faites un commit et poussez-le.

Typescript

Installation

Typescript est une dépendance de notre projet dont on a besoin que lors du développement ou de la construction du notre projet.

Les dépendances de ce genre s’installent avec l’option --save-dev ou -D.

pnpm add -D typescript

Une fois installé le paquet nous permet d’utiliser la commande pnpm tsc, qui invoque le compilateur typescript.

Ajoutez à votre package.json un script “build” qui lance la compilation du projet :

{
  "scripts": {
    "build": "tsc"
  }
}

Configuration

Le compilateur typescript peut être configuré pour un projet à l’aide d’un fichier tsconfig.json. Un peu comme on utiliserait un Makefile pour un projet en C/C++. tsc --init peut générer une configuration, mais elle ne serait pas adaptée à notre projet donc on va l’écrire nous-même.

En fonction de la version NodeJS sur laquelle on travaille (ici la version 22) on peut installer un paquet qui contient la configuration de base à passer à tsconfig.json.

pnmp add --save-dev @tsconfig/node22

La configuration à mettre dans tsconfig.json est la suivante :

{
    "$schema": "https://json.schemastore.org/tsconfig",
    "extends": "@tsconfig/node22/tsconfig.json",
    "compilerOptions": {
        "outDir": "dist/"
    },
    "include": ["src/**/*"],
    "exclude": ["**/*.test.ts"]
}

• $shema permet d’indiquer à votre IDE (vscode, nvim, jetbrains) comment vous aider avec l’auto-complétion ;
• extends charge la configuration que l’on vient d’installer pour la version 20 de Node ;
• outDir : le dossier dans où vont les fichiers compilés ;
• include: les fichiers à compiler ;
• exclude : les fichiers à ne pas compiler.

Sur VSCode seulement

Il peut être nécessaire de préciser à VSCode que la version typescript a utiliser est celle du dépôt :

1. faites ctrl+shift+p depuis un fichier TS ;
2. choisissez “Select TypeScript Version” ;
3. choisissez “Use Workspace Version”.

Charger des définitions de type

Prenons l’exemple de code suivant. Enregistrez-le sous src/index.ts.

interface Animal {
    make_sound(): void
};

class Cat {
    make_sound() {
        console.log("meow");
    }
}

class Dog {
    make_sound() {
        console.log("woof");
    }
}

function call_make_sound(animal: Animal) {
    animal.make_sound();
}

const cat = new Cat;
const dog = new Dog;

call_make_sound(cat);
call_make_sound(dog);

Utilisez pnpm build pour compiler votre projet. Vous devriez voir une erreur à propos de console.log qui n’est pas reconnu. Cela est du au fait que typescript n’a pas encore connaissance de types des objets et fonctions proposés par NodeJS. Cependant, ça n’a pas empêché tsc de produire quelque chose. Regardez le contenu de dist/index.js, il devrait ressembler à ceci :

;
class Cat {
    make_sound() {
        console.log("meow");
    }
}
class Dog {
    make_sound() {
        console.log("woof");
    }
}
function call_make_sound(animal) {
    animal.make_sound();
}
const cat = new Cat;
const dog = new Dog;
call_make_sound(cat);
call_make_sound(dog);
export {};

C’est très proche de ce que l’on a écrit en TypeScript, excepté que les types et l’interface ont disparu. C’est là tout le principe du TypeScript : on développe avec des types pour identifier tôt les erreurs (plutôt que d’attendre qu’elles se produisent à l’exécution) et on compile vers du JavaScript simple, qui peut être exécuté par notre runtime cible (NodeJS ou les navigateurs web).

Tout ça c’est bien beau mais ça nous explique pas comment se débarrasser de l’erreur de compilation de console.log.

Pour que tsc est connaissances des types de NodeJS, on doit installer :

pnpm add --save-dev @types/node

Après ça pnpm build compilera sans erreur.

Formatage et Lint avec Biome

Biome est un outil qui permet de formater et d’analyse statique (lint) de votre code source pour garantir une uniformité sur un projet et entre développeurs mais aussi pour assurer la qualité du code et pour trouver de potentiels bugs avant même qu’ils se produisent.

C’est une alternative à Prettier et à ESLint (couplé à ESLint typescript). Il a pour proposition de valeur d’être plus rapide (à l’utilisation et à la configuration). Il propose aussi des divergences avec la philosophie des outils qu’il remplace. Choisir un outil ou un autre relève ainsi d’un choix personnel ou propre à une équipe de développement.

pnpm add --save-dev @biomejs/biome

Ajoutez à votre dépôt la configuration suivante dans votre biome.json :

{
  "$schema": "https://biomejs.dev/schemas/2.2.2/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "ignoreUnknown": false
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space"
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  }
}

C’est une variation de la configuration que génère pnpm exec biome init.

Ajoutez les scripts suivant dans votre package.json:

  "scripts": {
    "build": "tsc",
    "lint": "biome lint",
    "format":" biome format --write",
    "autofix": "biome check --write"
  },

Enfin, assurez vous que votre éditeur arrive à formater votre code avec Biome. Cherchez dans la documentation ce qui s’applique à votre éditeur de code.

Tests avec vitest

vitest est un framework de tests, comme il en existe pléthore. Son avantage un petit peu comme biome, c’est qu’il est très facile à configurer (et par très facile j’entend qu’on ne va même pas créer de fichier de configuration). Ce qui n’est pas le cas jest l’un de ses plus populaires précurseurs. Vitest a aussi comme avantage d’être rapide et de s’utiliser facilement. (On peut dire que vitest met une vitesse à jest.)

Installez le avec :

pnpm add --save-dev vitest

Pour le tester créez un fichier src/repeat.ts :

export function repeat(text: string, times: number): string {
  const arr: string[] = [];
  while (times) {
    arr.push(text);
    times -= 1;
  }
  return arr.join("");
}

Et un fichier src/repeat.spec.ts :

import { expect, test } from "vitest";
import { repeat } from "./repeat.js";

test("repeats toto 3 times", () => {
  expect(repeat("toto", 3)).toBe("totototototo");
});

Enfin vous pouvez exécuter le test (et tout ceux que vous écrirez par la suite) grâce à :

pnpm vitest

Pour finir, ajoutez un script “test” dans votre package.json.

Conclusion

Tout ce que l’on vient de paramétrer va nous servir tout du long du module.

Ce sont des éléments que vous pouvez reprendre lors de vos projets personnels ou d’entreprise. Que ce soit les mêmes outils ou alors des équivalents.

En général ce dont chaque projet web à c’est :

• un runtime ;
• un gestionnaire de paquets ;
• un compilateur/un transpilateur pour :
  • passer du TS au JS,
  • faire un bundle,
  • convertir du JS vers une version plus ancienne (pour assurer la compatibilité avec des vieux navigateurs) ;
• un static analyser ;
• un formateur ;
• une bibliothèque de tests unitaires.