Tutoriel pour apprendre à utiliser l'outil JavaScript Grunt - Installation et mise en place dans un projet

À l'origine de Grunt en 2012, il y a Ben ALMAN, contributeur open source (jQuery, jQuery Mobile, Modernizr) et ambassadeur JavaScript et Bonnes Pratiques jQuery.

Sur le site officiel de Grunt, l'outil est défini comme un « Javascript task-runner » ou lanceur de tâches JavaScript. Qu'entend-on par là ?

• JavaScript : un module Node.js - par définition codé en JavaScript - permettant de créer des tâches codées également en JavaScript ;
• Lanceur de tâches : un outil permettant d'automatiser des tâches répétitives pour simplifier et accélérer les développements front-end.

Actuellement Grunt en est à la version 0.4.5. Cela signifie que l'équipe Grunt estime que l'API ne peut pas encore être considérée comme stable et que tout peut changer à tout moment.

Pour comprendre l'intérêt de l'automatisation de tâches, il faut savoir identifier ce que sont ces tâches en développement Web. Par exemple :

• Tests unitaires : vérifier le bon fonctionnement et la non-régression de l'application. Des frameworks de tests comme Jasmine, Mocha et QUnit existent en plugins Grunt ;
• Minification : réduire la taille des fichiers, par exemple en supprimant les espaces et retours à la ligne et en remplaçant les noms de variables et de fonctions par des noms le plus courts possible ;
• Concaténation : réduire le nombre de fichiers à charger en concaténant leur contenu dans un seul fichier ;

• Transcompilation : convertir d'un code source écrit dans un langage en un autre langage, comme :

  • LESS, SASS ou Stylus vers CSS,
  • CoffeeScript vers JavaScript,
  • Jade ou HAML vers HTML ;
• Linting : analyser du code pour la détection de probables erreurs. Cette détection se base sur un ensemble de règles syntaxiques et de bonnes pratiques comme utiliser les accolades en JavaScript même si le bloc ne contient qu'une instruction ;
• Déploiement : copier les distribuables dans les répertoires cibles des serveurs Web.

À la lecture de ces quelques exemples, vous êtes, je pense, en terrain connu et vous percevez déjà l'intérêt d'un seul outil capable de gérer tout cela pour vous. Comme vous le verrez par la suite, Grunt vous permet de réaliser tout cela et plus.

Le temps où un site Web n'était que pages statiques et liens est loin. Aujourd'hui, les interfaces se font riches et l'on parle non plus de sites, mais d'applications Web quand il s'agit de produits évolués, voire professionnels, comme Gmail ou Facebook. Le code front-end sous-jacent est de plus en plus complexe et il est important qu'il reste cohérent et maintenable.

Votre projet doit être DRY - Don't Repeat Yourself - et pour cela il vous faut standardiser certains processus comme :

• la gestion des dépendances web : cf. Bower ;
• l'automatisation des tâches récurrentes : Grunt.

Les principaux avantages de l'utilisation de Grunt :

• Utilité : gestion d'un grand nombre de processus récurrents à réaliser au build de l'application. Ces tâches peuvent être lancées manuellement, en réponse à la modification de certains fichiers ou par une autre tâche ;
• Rendement : gain de temps en automatisant les tâches avec un outil ;
• Consistance : moins d'interventions humaines, un même procédé pour toute l'équipe, une logique de build de l'application découplée du développement ;
• Efficacité : le développeur reste maintenant concentré sur le développement ;
• Communauté : une communauté forte assure un bon support en cas de problème et la mise à disposition d'un nombre substantiel de plugins. À l'heure actuelle, il y plus de 3000 plugins mis en ligne.

Non, il y a d'autres lanceurs de tâches JavaScript sur le marché. Le plus sérieux concurrent actuellement étant Gulp.

Grunt et ses plugins sont des packages Node.js, c'est pourquoi leur installation passe par npm, le gestionnaire de modules de Node.js. Le prérequis sous-jacent est donc que Node.js et npm doivent être installés sur votre poste de travail.

Pour installer Node.js dans votre environnement préféré (Windows, Mac OS X, Linux, Solaris), visitez le site officiel de Node.js.

Pour vous documenter sur l'utilisation de npm, visitez le site officiel de npm.

Vous devez tout d'abord installer globalement le CLI - ou interface ligne de commande - de Grunt.

$ npm install -g grunt-cli

L'installation de ce package Node.js met la commande grunt dans votre path système, ce qui permet de l'utiliser depuis n'importe quel répertoire.

Cela n'installe pas le lanceur de tâches lui-même ! La fonction du CLI est de fournir une commande unique - grunt - pour lancer n'importe quelle version du lanceur de tâches Grunt installée près d'un Gruntfile. Cela permet la cohabitation de versions différentes de Grunt sur la même machine.

Chaque fois que la commande grunt est exécutée sur un répertoire, ça recherche le Grunt installé localement en utilisant le système require() de Node.js. Grâce à cela, vous pouvez exécuter la commande depuis n'importe quel sous-répertoire du projet.

Si une version de Grunt est détectée, le CLI charge la version locale de la bibliothèque Grunt, applique la configuration du Gruntfile et exécute les tâches demandées.

Comme je vous l'ai déjà dit un peu plus tôt, les plugins grunt sont des modules Node.js et npm est le gestionnaire de modules Node.js.

Il permet de publier des modules dans le dépôt npm sous un nom unique, ses objectifs étant le partage et la récupération de code depuis un dépôt public.

Le système de modules Node.js est une implémentation de la spécification CommonJS. CommonJS décrit une syntaxe simple pour les programmes JavaScript pour importer (require()) d'autres programmes JavaScript dans leur contexte. Cette fonctionnalité aide grandement à la création de systèmes modulaires en simplifiant le processus de SoC (Separation of Concerns). Dans Node.js, tout fichier JavaScript peut être vu comme un module individuel.

Qu'est-ce qu'un module ?

Un module est un programme JavaScript pouvant être chargé avec require() dans un programme Node.js. Cela peut être :

• un répertoire contenant un fichier package.json contenant lui-même un objet JSON avec un champ main ;
• un répertoire contenant un fichier index.js ;
• un fichier JavaScript.

Qu'est-ce qu'un package ?

Un package peut être :

1. Un répertoire contenant un programme décrit par un fichier package.json ;
2. Une archive compressée au format gzip contenant (1) ;
3. Une URL sur un (2) ;
4. Un <nom>@<version> publié dans le registre avec (3) ;
5. Un <nom>@<tag> qui pointe sur (4) ;
6. Un <nom> dont le dernier tag satisfait (5) ;
7. Une URL git qui, quand elle est clonée, donne un (1).

Grunt et ses plugins sont des packages Node.js, et donc des modules Node.js. Les modules sont installés par npm dans des répertoires node_modules.

Partons d'un projet Web video-library dont l'arborescence initiale est la suivante :

Votre application est fonctionnelle, mais vous voulez utiliser Grunt pour automatiser diverses tâches. Ces tâches auront pour but de créer un livrable de votre application à partir des fichiers source. Il faut donc organiser votre projet de sorte à clairement identifier le code d'origine du code distribuable généré. L'usage est donc d'organiser son projet de manière à avoir le code d'origine dans un répertoire source et de prévoir au même niveau un répertoire target où seront générés les fichiers distribuables.

L'utilisation de Grunt nécessitera la présence des deux fichiers package.json et Gruntfile.js à la racine de votre projet. L'installation de Grunt et de ses plugins implique la création par npm du répertoire node_modules. La structure du projet va devenir donc celle-ci :

Maintenant que l'arborescence de votre projet est en place, vous pouvez rechercher et installer des packages !

npm est un utilitaire en ligne de commande. Vous pouvez l'utiliser avec l'invite de commande Windows, Windows PowerShell, Terminal, Git Bash, etc. L'objectif premier de npm est la recherche et l'installation de modules Node.js.

Utilisez la commande npm search suivie d'un ou plusieurs mots-clés pour obtenir la liste des packages qui correspondent. Pour chercher un plug-in Grunt, utilisez le mot-clé gruntplugin qui est le tag recommandé par l'équipe Grunt. Les mots-clés sont recherchés dans le fichier package.json qui contient les métadonnées d'un package : title, tags, description, dependencies, etc.

$ npm search <mots-clés>

Vous avez identifié un package qui vous semble intéressant ? Affichez le contenu de son package.json pour obtenir plus d'informations !

$ npm info <nom_du_package>

Ce package vous plait ? Visitez son dépôt avec la commande npm repo qui ouvre votre navigateur par défaut.

$ npm repo <nom_du_package>

Pour installer le package, utilisez la commande npm install. Vous pouvez l'installer globalement dans le sous-répertoire node_modules du répertoire de npm défini dans le PATH pour l'utiliser comme utilitaire en ligne de commande,

$ npm install -g <nom_du_package>

ou localement dans le répertoire node_modules d'un projet s'il s'agit d'une dépendance de l'un de vos projets.

$ npm install <nom_du_package>

$ npm install <nom_du_package> --save-dev

Pour installer localement un package, l'utilitaire de ligne de commande que vous utilisez doit pointer au choix :

1. Sur le répertoire de votre projet qui contient le fichier package.json de votre projet ;
2. Sur un répertoire dont le premier parent contenant un fichier package.json est le répertoire de (1) ;
3. Sur un répertoire de votre projet sans package.json à son niveau ou dans sa parentèle.

Dans les cas (1) et (2), npm détecte le projet auquel ajouter la dépendance et cet ajout se traduit par :

• le téléchargement du package dans un répertoire node_modules au même niveau que le package.json détecté ;
• l'ajout d'une référence au package téléchargé dans les dépendances du projet par complétion de la variable dependencies du fichier package.json de votre projet si l'option --save-dev est utilisée.

Dans le cas (3), npm :

• télécharge le package dans un répertoire node_modules au niveau du répertoire pointé par l'utilitaire de ligne de commande.

Considérant que l'utilitaire de ligne de commande pointe sur le répertoire sub_nested pour le projet top, illustrons les trois cas possibles pour l'installation du package grunt-contrib-uglify :

$ npm install grunt-contrib-uglify

package.json est le fichier qui décrit un package Node.js. Il contient toutes les métadonnées et les dépendances du projet. Ces informations sont nécessaires à npm pour installer Grunt et ses plugins.

package.json contient un unique objet JSON (JavaScript Object Notation). Ce fichier peut être généré par npm ou créé manuellement. À partir de ce fichier, placé à la racine de votre projet, npm est capable d'installer toutes les dépendances du projet !

Il existe plusieurs façons de créer ce fichier :

1. En suivant les directives de la commande npm init ;

2. En partant d'un exemple minimaliste

    

   Sélectionnez

   1.
   2.
   3.
   4.
   

   {
     "name": "mon projet",
     "version": "0.1.0"
   }
   

3. En partant d'un template grunt-init.

Voici la liste des principaux champs que l'on trouve dans l'objet JSON du fichier package.json :

• name string : le nom du package ;
• version string : la version du package ;
• description string : la description du package. Ce champ est scruté par npm search;
• keywords string[] : les mots-clés du package. Cette liste est scrutée par npm search;
• license string : la licence pour l'utilisation du package ;
• author string : l'auteur du package ;
• main string : l'ID du module qui est le point d'entrée primaire du programme ;
• dependencies hash : hash des noms de packages/plage de versions (SemVer) requis par le package pour fonctionner ;
• devDependencies hash : hash des noms de packages/plage de versions (SemVer) pour les tests et la transcompilation du package ;
• repository hash : définition du dépôt du package. L'objet est composé des champs type (par exemple git, svn…) et url.

Créons ce fichier dans notre projet video-library avec npm init en suivant les étapes proposées par la commande :

Un fichier package.json basique vient d'être créé dans le projet.

Installons maintenant le lanceur de tâches de Grunt et les plugins grunt-contrib-uglify et grunt-processhtml avec la commande npm install :

L'installation commence par deux messages d'alertes :

• il n'y a pas d'indication de repository pour le package video-library dans package.json ;
• il n'y a pas de fichier README.md à la racine du répertoire du package video-library.

Rien de grave :

• si le projet est sur un dépôt, renseignez le champ repository dans le package.json ;
• mettez à la racine du projet un fichier README.md dans lequel vous expliquez ce qu'est ce projet.

Après ces alertes, vous voyez les packages installés dans leur version courante - puisqu'aucun numéro de version n'a été précisé dans la commande npm install - et l'arbre des dépendances de ceux-ci - qui sont également chargés.

Le répertoire node_modules, s'il n'existait pas, a été créé. Les trois packages grunt, grunt-contrib-uglify et grunt-processhtml ont été chargés dans le répertoire.

Par contre le fichier package.json n'a pas été modifié et aucune mention n'est faite des dépendances du projet video-library sur ces trois packages. Pour que le package.json soit automatiquement modifié par la commande npm install, utilisez l'option --save-dev.

"devDependencies": {
  "grunt": "^0.4.5",
  "grunt-contrib-uglify": "^0.5.1",
  "grunt-processhtml": "^0.3.3"
}

L'avantage d'enregistrer les dépendances dans le package.json est que si vous prenez en main un projet sans le répertoire node_modules, mais avec le fichier package.json, vous pouvez installer toutes les dépendances avec la commande npm install sans paramètre.

Les packages Grunt ont été identifiés comme devDependencies, ce qui signifie qu'ils ne sont pas nécessaires au package quand celui-ci sera distribué.

Une version de Grunt et deux plugins sont installés dans le projet. Il ne reste plus qu'à les utiliser. Pour orchestrer cela, il y a le fichier Gruntfile.

La commande grunt cherche le fichier Gruntfile de manière similaire à npm avec package.json. Le Gruntfile - .js ou .coffee - est un fichier JavaScript ou CoffeeScript à la racine du projet, au même niveau que le package.json. Il est constitué des éléments suivants :

• Fonction wrapper ;
• Configuration du projet et des tâches ;
• Chargement des plugins et des tâches ;
• Tâches personnalisées.

Dans la suite du tutoriel, le Gruntfile considéré sera un fichier JavaScript Gruntfile.js.

III-E-1. Fonction wrapper▲

module.exports = function(grunt) {
  // Code relatif à grunt
};

III-E-2. Configuration du projet et des tâches▲

//Configuration du projet
grunt.initConfig({
  uglify: {
    options: {
      banner: '/*Mon package : <%=grunt.template.today("yyyy-mm-dd")%>*/\n'
    },
    build: {
      src: 'source/monPackage.js',
      dest: 'target/monPackage.min.js'
    }
  }
});

III-E-3. Chargement des plugins et des tâches▲

// Charge le plugin qui fournit la tâche 'uglify'.
grunt.loadNpmTasks('grunt-contrib-uglify');

III-E-4. Tâches personnalisées▲

// Une tâche très très simple.
grunt.registerTask('simple', 'Elle trace ma tâche.', function() {
  grunt.log.write('Trace un truc...').ok();
});

// Tâches par défaut.
grunt.registerTask('default', ['uglify', 'simple']);

III-E-5. Un Gruntfile.js complet▲

module.exports = function(grunt) {
  //Configuration du projet
  grunt.initConfig({
    uglify: {
      options: {
        banner: '/*Mon package : <%=grunt.template.today("yyyy-mm-dd")%>*/\n'
      },
      build: {
        src: 'source/monPackage.js',
        dest: 'target/monPackage.min.js'
      }
    }
  });
 
  // Charge le plugin qui fournit la tâche 'uglify'.
  grunt.loadNpmTasks('grunt-contrib-uglify');
 
  // Une tâche très très simple.
  grunt.registerTask('simple', 'Elle trace ma tâche.', function()   {
    grunt.log.write('Trace un truc...').ok();
  });
 
  // Tâches par défaut.
  grunt.registerTask('default', ['uglify', 'simple']);
};