Initialiser un projet Node.js sous TypeScript et ESLint

Dans cet article nous allons voir comment démarrer un projet Node.js de zéro en utilisant le superset TypeScript. Nous y imbriquerons également ESLint, un linter permettant une analyste statique du code. Vous aurez ainsi les outils pour compiler votre projet JavaScript à l’aide de TypeScript.

TypeScript est un langage open source développé par Microsoft dont le but est de palier les défauts du langage JavaScript, à savoir :

• Fournir un système de typage des objets optionnel
• Permettre aux développeurs d’utiliser des fonctionnalités non supportées par les moteurs JavaScript actuels
• Offrir un compilateur permettant de détecter les bugs et les erreurs de typage tel qu’on peut en trouver pour les langages objets comme C# ou Java.

Initialisation du projet avec npm

Avant d’aller plus loin, vous devez tout d’abord installer npm, qui est un outil de partage de module JavaScript. Il est fourni avec l’installation de Node.js.

Je vous invite également à installer en parallèle l’outil de commande Git Bash. Via l’intégration Windows, vous aurez ainsi la possibilité d’exécuter plus facilement des commandes npm depuis vos projets. Mais également depuis le terminal de Visual Studio Code, un éditeur fournit par Microsoft que je vous recommande fortement pour vos développements FrontEnd.

Une fois tous ces outils installés, lancez un bash git (bouton droit > Git Bash Here) depuis le dossier devant contenir votre projet (ou depuis le terminal de Visual Studio Code), puis tapez la commande suivante:

npm init -y

Sans le paramètre -y vous seriez amené à répondre à différentes questions qui permettent de générer à terme le fichier package.json suivant à la racine de votre projet.

{
  "name": "nodejs-with-typesript",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Définition des dépendances

Nous allons maintenant procéder à l’installation des dépendances de développement (TypeScript, ESLint …) pour notre projet Node.js. L’ensemble des commandes est marqué de l’attribut --save-dev. Grâce à ça les modules ne seront utilisés que pour la compilation de notre code et ne seront pas distribués dans le build final de notre projet JS, allégeant ainsi les binaires.

Exécutez l’ensemble des commandes ci-dessous :

npm install typescript --save-dev
npm install eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser --save-dev
npm install @types/node --save-dev

Vous pourriez également utiliser l’attribut -g en lieu et place de --save-dev pour indiquer à npm d’installer globalement les dépendances, mais il est préférable de le faire de cette manière car cela vous permettra de maintenir des versions de dépendances différentes entre vos projets sans subir d’éventuels « breaking changes ».

@types/node fournit un fichier de déclaration de type (ils sont reconnaissable à leur extension .d.ts) pour l’API node. Cela permet à TypeScript d’obtenir une auto-completion sur les objets de la librairie ainsi qu’une liste de types autorisés. N’hésitez pas à vérifier leurs existences sur npm ou github, ces déclarations, quand elles ne sont pas présentes, sont souvent créées en parallèle des librairies pour permettre la compatibilité avec TypeScript.

Ajout du fichier tsconfig.json

C’est dans le fichier tsconfig.json que l’on définit les options de compilation pour TypeScript. Il existe plusieurs moyens de définir le fichier. La première chose à faire est de l’initialiser manuellement à l’aide de la commande npx suivante :

npx tsc --init

Cela va vous générer un fichier avec les commandes par défaut d’activées. Libre à vous ensuite de décommenter et / ou supprimer les valeurs que vous ne souhaitez pas utiliser pour la compilation. Vous pouvez également ajouter des paramètres à la commande npx pour activer et définir des valeurs à la création. N’hésitez pas à vous rendre sur la documentation du fichier pour connaître la fonction des différentes options.

Si vous n’êtes pas sûr des options à activer vous pouvez très bien passer par des configurations recommandées en étendant votre fichier. Il suffit de se rendre sur la page GitHub qui regroupe les fichiers par environnement et d’installer le module qui vous convient de cette manière :

npm install --save-dev @tsconfig/recommended

Il suffit ensuite d’étendre votre configuration avec le module que vous avez choisi en modifiant le fichier tsconfig.json à la racine de votre projet en y ajoutant un attribut extends :

{
  "compileOnSave": false,
  "extends": "@tsconfig/recommended/tsconfig.json",
  "compilerOptions": {
      "outDir": "./dist/",
      "types": ["node"],
      "typeRoots": ["node_modules/@types"],
      "noImplicitAny": true,
      "moduleResolution": "node"
    },
  "include": ["./src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}

J’ai également ajouté quelques attributs supplémentaires pour la bonne prise en charge sous node.js, mais aussi des paramètres définissant le dossier de sortie des fichiers JS compilés via outDir. L’attribut exclude indique au compilateur les fichiers / dossiers à ne pas prendre en compte. Au contraire de l’attribut include qui indique où précisément la compilation des fichiers doit être effectuée. Vous aurez compris que nos fichiers .ts devront être positionnés dans un dossier src à créer à la racine de notre projet.

Configuration d’ESLint

Nous y sommes presque. Il nous reste encore ESLint, notre analyseur de code statique, à configurer avant de commencer à compiler notre code TypeScript. ESLint a pour mission de formater le code en fonction de règles que vous aurez dicté via un fichier de configuration. L’avantage d’établir des règles, surtout dans une équipe de développement, est d’unifier le code de sortie de manière à ce qu’il soit lisible par l’ensemble de l’équipe. De la même manière que pour le fichier tsconfig.json de TypeScript, ESLint dispose d’une commande pour initialiser son fichier :

npx eslint --init

Plusieurs questions vous seront posées, mais pour les besoins de l’article et pour optimiser la compatibilité avec TypeScript et node.js je vous invite à écraser et à utiliser la configuration suivante :

{
  "root": true,
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 6,
    "sourceType": "module",
    "project": "./tsconfig.json"
  },
  "plugins": ["@typescript-eslint"],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/eslint-recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking"
  ]
}

Il va également falloir indiquer à ESLint où il ne faut pas piocher pour parser le code. Plusieurs choix s’offrent à vous :

• Ajouter un attribut ignorePatterns à votre fichier .eslintrc
• Ajouter un attribut eslintIgnore au fichier package.json
• Créer un fichier .eslintIgnore à la racine du projet

N’hésitez pas à consulter la documentation pour connaître les formats attendus pour chaque type de configuration.

Dans notre cas nous utiliserons le fichier et y ajouterons notre dossier de build. Il est également intéressant de savoir que des règles par défaut inclus déjà le dossier node_modules.

dist

Scripting et exécution

Maintenant que tout ce petit monde est configuré, il ne reste plus qu’à les exécuter. Pour cela nous allons ajouter des commandes scriptées depuis le fichier package.json. Cela permettra d’exécuter ces commandes via npm pour lancer une compilation, le linter ou démarrer notre projet node. Modifiez votre fichier package.json comme suit :

[...]
"scripts": {
    "start": "node ./dist/index.js",
    "compile": "rimraf ./dist && tsc",
    "lint": "eslint . --ext .ts",
    "test": "echo \"Error: no test specified\" && exit 1"
},
[...]

Toute commande via npm s’exécute de la manière suivante : npm run <script_label>, où <script_label> corresponds ici à compile, lint ou test. Ces noms sont à votre bon vouloir, vous pourriez très bien mettre build à la place de compile.

start est un nom réservé qui ne requière pas la présence de run et peut donc s’écrire npm start pour lancer directement notre projet node.

Autre point important, l’utilisation du module rimraf dans le script de compilation, que je vous invite à installer :

npm install --save-dev rimraf

Je m’en sert pour nettoyer le dossier de destination des fichiers compilés par TypeScript (même fonction que la commande rm -rf). Ca évite d’avoir des références fantômes ou non désirées. Libre à vous de l’utiliser ou pas.

Vous êtes fin prêt pour démarrer le développement de votre projet sous TypeScript avec Node.js.

Hello World !

Dans un premier temps, installez le module console-stamp depuis votre terminal :

npm install --save-dev @types/console-stamp
npm install --save console-stamp

Puis, depuis le dossier src que vous avez créé plus haut, ajoutez un fichier index.ts et ajoutez le code suivant :

import consoleStamp from "console-stamp";

// Initialisation du format des logs dans la console.
consoleStamp(console, { format: ":date(yyyy-mm-dd'T'HH:MM:ss.l'Z')" });

console.log("Hello World !");

Enfin exécutez consécutivement les commandes scriptées ci-dessous :

npm run lint
npm run compile
npm start

Si tout c’est déroulé correctement, vous devriez avoir comme valeur dans votre terminal Git Bash ou Visual Studio Code quelque chose de ce genre. :

[2021-05-10P16:53:32.063GMT+0200] Hello World !

Au pire, vous avez maintenant un debugger performant qui vous indiquera le problème 🙂

Conclusion

Nous avons vu dans cet article comment mettre en place un environnement de développement node.js se basant sur TypeScript pour la compilation du code. Nous avons également vu comment installer et utiliser un linter et plus spécifiquement ESLint pour unifier le code produit. Enfin, nous avons utilisé le scripting d’npm pour lancer des commandes.

Il est tout à fait possible d’aller plus loin pour effectuer du Cold ou Hot Reloading, d’automatiser le déploiement des packs et la construction de nos builds à l’aide de bundler tel que Webpack. Pour cela je vous invite à regarder l’article suivant : Initialiser un projet React sous TypeScript avec Webpack

Références

• Dépôt GitHub du projet : https://github.com/INGENIANCE/NodeJs-With-TypeScript
• Documentation TypeScript : https://www.typescriptlang.org/docs/
• Documentation ESLint: https://eslint.org/docs/user-guide/getting-started
• Documentation npm: https://docs.npmjs.com/
• Documentation Node.js: https://nodejs.org/en/docs/
• Initialiser un projet React sous TypeScript avec Webpack
• Pourquoi utiliser TypeScript ?