Tutoriel pour apprendre à utiliser l'outil JavaScript Grunt - Présentation de l'API

Initialise l'objet de configuration du projet. L'objet configObject est utilisé par les tâches et est accessible via la méthode grunt.config.

grunt.config.init(configObject)
grunt.initConfig(configObject)

Met en échec la tâche courante si au moins l'une des propriétés requises de la configuration est manquante, null ou undefined. Une ou plusieurs propriétés ou tableaux de propriétés de la configuration peuvent être passés en paramètre.

grunt.config.requires(p1 [, p2 [, …]])
this.requiresConfig(p1 [, p2 [, …]]) // depuis le contexte d'une tâche

Retourne une valeur brute de la configuration du projet Grunt, sans traiter les chaînes template <% %>. Si la propriété spécifiée existe, sa valeur est retournée, sinon null. Si aucune propriété n'est spécifiée, une copie de l'objet config est retournée.

grunt.config.getRaw([prop])

Traite une valeur en évaluant récursivement les templates <% %>.

grunt.config.process(value)

module.exports = function(grunt) {
  grunt.config.init({
    bar : "C'est mal bar' !",
    foo : "<%= bar %>"
  });
 
  grunt.registerTask("default", "Trace des choses...", function() {
    var processed = grunt.config.process(grunt.config("foo"));
    grunt.log.write(processed).ok(); // retourne "C'est mal bar' !"
  );
};

Retourne une valeur de la configuration du projet Grunt. Si la propriété spécifiée existe, sa valeur est retournée, sinon null. Si aucune propriété n'est spécifiée, une copie de l'objet config est retournée. Les templates <% %> sont traités récursivement par appel à la méthode grunt.config.process.

grunt.config.get([prop])

Assigne une valeur à une propriété de la configuration du projet Grunt et la retourne.

grunt.config.set(prop, value)

Retourne ou assigne une propriété de la configuration du projet Grunt. Cette méthode est un alias de grunt.config.set et grunt.config.get.

grunt.config([prop [, value]])
 
grunt.config(prop); // alias de grunt.config.get(prop)
grunt.config(prop, value); // alias de grunt.config.set(prop, value)

Échappe les points dans la propriété spécifiée

grunt.config.escape(propString)

module.exports = function(grunt) {
  grunt.config.init({
    foo: {
      bar: "value"
    }
  });
 
  grunt.registerTask("default","Trace des choses... ", function() {
    grunt.log.write(grunt.config.escape("foo.bar")).ok(); // retourne "foo\.bar"
  });
};

Fusionne récursivement les propriétés de l'objet configObject à la configuration du projet Grunt.

grunt.config.merge(configObject)

Enregistre sous un alias une liste d'alias de tâches ou une tâche. Cette méthode a deux signatures :

// liste d'alias
grunt.task.registerTask(taskName, taskList)
grunt.registerTask(taskName, taskList)

// tâche
grunt.task.registerTask(taskName, description, taskFunction)
grunt.registerTask(taskName, description, taskFunction)

Si une liste d'alias est spécifiée, la nouvelle tâche sera un alias pour une ou plusieurs autres tâches. Quand cette tâche est lancée, les tâches de la taskList sont lancées dans l'ordre spécifié. L'argument taskList doit être un tableau d'alias de tâche.

Si une description et une taskFunction sont passées, la fonction est exécutée quand la tâche est lancée. La description est affichée quand la commande grunt --help est exécutée.

grunt.task.registerTask('default', ['jshint', 'qunit', 'concat:dist', 'uglify:dist']);
 
grunt.task.registerTask(
  'foo',
  'Une tâche simple pour tracer des choses',
  function(arg1, arg2) {
    if (arguments.length === 0) {
      grunt.log.writeln(this.name + ", pas d'argument");
    }
    else {
      grunt.log.writeln(this.name + ", " + arg1 + " " + arg2);
    }
  }
);

Enregistre une multitâche ou tâche à cibles multiples. Une multitâche est une tâche qui se répète pour chacune de ses sous-propriétés (ou targets) si aucune target n'est spécifiée.

grunt.task.registerMultiTask(taskName, description, taskFunction)
grunt.registerMultiTask(taskName, description, taskFunction)

module.exports = function(grunt) {
  grunt.initConfig({
    log: {
      foo: [1, 2, 3],
      bar: "Salut monde !",
      oque: false
    }
  });
 
  grunt.task.registerMultiTask("log", "Trace des choses…", function() {
    grunt.log.writeln(this.target + ": " + this.data);
  });
};

Dans l'exemple précédent, l'exécution du log multitâche provoque l'écriture dans la console pour chacune des trois sous-propriétés de la propriété log de la configuration du projet. Par contre, en indiquant la target foo, la tâche ne s'exécute qu'une fois pour la target spécifiée.

Met en échec la tâche si une autre tâche est en échec ou n'a jamais été lancée.

grunt.task.requires(taskName)

Vérifie en fonction de son nom si une tâche existe parmi les tâches enregistrées. Retourne un booléen.

grunt.task.exists(name)

Renomme une tâche. Cela peut être utile pour remplacer le comportement par défaut d'une tâche, tout en conservant l'ancien nom.

grunt.task.renameTask(oldname, newname)
grunt.renameTask(oldname, newname)

Charge les fichiers de tâches depuis le chemin spécifié, relatif au répertoire du Gruntfile. Cette méthode peut être utilisée pour charger des fichiers de tâches depuis un plugin Grunt local.

grunt.task.loadTasks(tasksPath)
grunt.loadTasks(tasksPath)

Charge les tâches du plugin Grunt spécifié. Ce plugin doit être installé localement via npm et relativement au Gruntfile.

grunt.task.loadNpmTasks(pluginName)
grunt.loadNpmTasks(pluginName)

Met en file d'attente une ou plusieurs tâches. Chaque tâche spécifiée dans taskList sera lancée immédiatement après la fin de l'exécution de la précédente. La liste de tâches peut être un tableau de tâches ou une suite d'arguments.

grunt.task.run(taskList)

grunt.registerTask('foo-bar-oque', 'Met en file d\'attente.', function() {
  grunt.task.run('foo', 'bar:man', 'oque');
  grunt.task.run(['foo', 'bar:man', 'oque']);
});

Vide la file d'attente. À moins que des tâches soient de nouveau mises en file d'attente, plus aucune tâche ne sera lancée.

grunt.task.clearQueue()

Normalise l'objet de configuration d'une target de tâche dans un tableau de correspondances de fichiers src-dest.

grunt.task.normalizeMultiTaskFiles(data [, targetname])

grunt.registerTask('normalize', function(pattern) {
  var result = grunt.task.normalizeMultiTaskFiles(['files/**/*'], "myTargetName");
  grunt.log.writeln(JSON.stringify(result));
});

Lit et retourne un contenu de fichier. Retourne une chaîne de caractères, à moins que options.encoding soit null, auquel cas la méthode retourne un Buffer.

grunt.file.read(filepath [, options])
grunt.file.readJSON(filepath [, options]) // contenu parsé en JSON
grunt.file.readYAML(filepath [, options]) // contenu parsé en YAML

Les propriétés reconnues dans l'objet options sont :

var options = {
  // Si aucun encodage n'est spécifié, par défaut à grunt.file.defaultEncoding.
  // S'il est spécifié à null, retourne un Buffer non décodé au lieu d'une chaîne.
  encoding: encodingName
};

Écrit le contenu spécifié dans un fichier en créant le chemin si nécessaire.

grunt.file.write(filepath, contents [, options])

Les propriétés reconnues dans l'objet options sont :

var options = {
  // Si aucun encodage n'est spécifié, par défaut à grunt.file.defaultEncoding.
  // Si 'contents' est un Buffer, l'encodage est ignoré.
  encoding: encodingName
};

Copie un fichier source à une destination en créant le chemin si nécessaire.

grunt.file.copy(srcpath, destpath [, options])

Les propriétés reconnues dans l'objet options sont :

var options = {
  // Si aucun encodage n'est spécifié, par défaut à grunt.file.defaultEncoding.
  // Si null, la fonction 'process' reçoit un Buffer au lieu d'un String.
  encoding: encodingName,
  // bool processFunction(srcPath, srcContent, destPath)
  // Si la fonction retourne 'false', la copie est interrompue.
  process: processFunction,
  // Patterns sur le chemin de la source. Si aucun ne correspond,
  // le fichier ne sera pas traité par la fonction 'process'.
  // Si globbingPatterns='true', le traitement n'aura pas lieu.
  noProcess: globbingPatterns
};

Supprime le chemin spécifié. Cela supprimera les fichiers et les répertoires de manière récursive.

grunt.file.delete(filepath [, options])

Les propriétés reconnues dans l'objet options sont :

var options = {
  // Permet de supprimer en dehors du répertoire de travail courant.
  // Cette option permet être surchargée par l'option de ligne de commande --force.
  force: true
};

Fonctionne comme mkdir -p0777&(~process.umask()). Crée un chemin avec tous les répertoires intermédiaires. Si mode n'est pas spécifié, la valeur par défaut est 0777&(~process.umask()).

grunt.file.mkdir(dirpath [, mode])

Retourne un booléen indiquant si le chemin spécifié existe, est un lien, un chemin ou un fichier ; retourne faux si le chemin n'existe pas.

Comme la méthode path.join de Node.js, ces méthodes joignent tous les arguments ensemble et normalisent le chemin résultant.

grunt.file.exists(path1 [, path2 [, ...]])
grunt.file.isLink(path1 [, path2 [, ...]])
grunt.file.isDir (path1 [, path2 [, ...]])
grunt.file.isFile(path1 [, path2 [, ...]])

Retourne un booléen indiquant si le chemin spécifié est absolu.

Comme la méthode path.join de Node.js, ces méthodes joignent tous les arguments ensemble et normalisent le chemin résultant.

grunt.file.isPathAbsolute(path1 [, path2 [, ...]])

Retourne un booléen indiquant si tous les chemins spécifiés se réfèrent au même chemin.

grunt.file.arePathsEquivalent(path1 [, path2 [, ...]])

Retourne un booléen indiquant si tous les chemins descendants sont contenus par le chemin ascendant.

grunt.file.doesPathContain(ancestorPath, descendantPath1 [, descendantPath2 [, ...]])

Change le chemin de travail courant. Par défaut tous les chemins sont relatifs au Grunfile.

Comme la méthode path.join de Node.js, ces méthodes joignent tous les arguments ensemble et normalisent le chemin résultant.

grunt.file.setBase(path1 [, path2 [, ...]])

Si une tâche est asynchrone, cette méthode doit être invoquée pour indiquer à Grunt d'attendre. Elle retourne une fonction done qui doit être appelée quand la tâche s'est terminée. false ou un objet erreur peut être passé à la méthode done pour indiquer à Grunt que la tâche a échoué.

Si la méthode this.async n'est pas appelée, la tâche s'exécutera de manière synchrone.

// Indique à Grunt que la tâche est asynchrone.
var done = this.async();
// Le code asynchrone.
setTimeout(function() {
  // Simulons une erreur de manière aléatoire.
  var error = Math.random() > 0.5;
  // Terminé!
  done(error);
}, 1000);

Si une tâche dépend du succès de l'exécution d'une ou plusieurs autres tâches, cette méthode peut être utilisée pour forcer Grunt à s'arrêter si cette ou ces autres tâches n'ont pas été exécutées ou ont échoué. La liste de tâches peut être un tableau ou une suite de noms de tâches.

this.requires(tasksList)

Met en échec la tâche courante si au moins l'une des propriétés de configuration requises est manquante. Un tableau ou une suite de propriétés de configuration peuvent être spécifiés.

this.requiresConfig(prop1 [, prop2 [, ...]])

Cette méthode est un alias de la méthode grunt.config.requires.

Le nom de la tâche, tel que défini avec grunt.registerTask. Dans le cas d'une multitâche, le nom est le même, quelle que soit la target.

module.exports = function(grunt) {
  grunt.initConfig({
    exemple: {
      foo: [1, 2, 3],
      bar: 'Salut monde !',
      oque: false
    }
  });
 
  grunt.task.registerMultiTask('exemple', 'Un exemple de tâche…', function() {
    grunt.log.writeln(this.name);
  });
};

Si la tâche est renommée avec grunt.task.renameTask, la propriété this.name renvoie le nouveau nom.

Le nom de la tâche, incluant tous les arguments ou flags séparés par un deux-points spécifié dans la ligne de commande. Par exemple, si une tâche exemple est exécutée avec la commande grunt exemple:foo, dans la tâche, this.nameArgs sera exemple:foo.

Si la tâche est renommée avec grunt.task.renameTask, la propriété this.nameArgs renvoie le nouveau nom.

Un tableau d'arguments passés à la tâche. Par exemple, si une tâche « exemple » est exécutée avec la commande grunt exemple:foo:tez, dans la tâche, this.args sera ["foo", "tez"].

Pour les multitâches, la target courante est omise du tableau this.args.

Un objet généré à partir des arguments passés à la tâche. Par exemple, si une tâche exemple est exécutée avec la commande grunt exemple:foo:tez, dans la tâche, this.flags sera {foo: true, tez: true}.

Pour les multitâches, la target courante est omise de l'objet this.flags.

Le nombre d'appels à grunt.log.error pendant l'exécution de la tâche. Cela peut être utilisé pour mettre en échec la tâche si des erreurs sont logées pendant l'exécution de la tâche.

Retourne un objet options. Les propriétés de l'argument optionnel defaultsObj seront surchargées par les propriétés de l'objet options au niveau de la tâche, qui seront également surchargées dans les multitâches par les propriétés de l'objet options au niveau de la target.

this.options([defaultsObj])

Cet exemple montre comment une tâche peut utiliser la méthode this.options :

var options = this.options({
  enabled: false,
});
 
doSomething(options.enabled);

Contient le nom de la target courante.

Tous les fichiers spécifiés en utilisant un format et des options supportés par Grunt, un motif ou une correspondance dynamique seront automatiquement normalisés dans un format unique : un tableau de fichiers.

Cela signifie que les tâches ne gèrent pas la normalisation des chemins de fichiers. L'action est réalisée en amont par Grunt.

La tâche doit itérer sur le tableau this.files en utilisant les propriétés src et dest de chaque objet du tableau. La propriété this.files sera toujours un tableau. La propriété src sera également toujours un tableau, car il est possible d'avoir plusieurs sources pour un fichier destination.

Comme il est possible que des fichiers non existants soient inclus dans les sources, il est préférable de tester l'existence des fichiers source avant de les utiliser.

Cet exemple montre comment une tâche simple de concaténation peut utiliser la propriété this.files :

this.files.forEach(function(file) {
  var contents = file.src.filter(function(filepath) {
    // Supprimer les fichiers non existants (à vous de filtrer ou alerter).
    if (!grunt.file.exists(filepath)) {
      grunt.log.warn('Fichier source "' + filepath + '" non trouvé.');
      return false;
    }
    else {
      return true;
    }
  }).map(function(filepath) {
    // Lit et retourne le fichier source.
    return grunt.file.read(filepath);
  }).join('\n');
 
  // Écrit les contenus joints dans le fichier destination filepath.
  grunt.file.write(file.dest, contents);
 
  // Imprime un message de succès.
  grunt.log.writeln('Fichier "' + file.dest + '" créé.');
});

Si vous avez besoin des propriétés de l'objet file d'origine, elles sont disponibles sur chaque objet file dans la propriété orig.

Tous les fichiers spécifiés par n'importe quel format sont réduits à un seul tableau. Si votre tâche est en « lecture seule » et ne tient aucun compte des chemins de destination, utilisez ce tableau plutôt que this.files.

Cet exemple montre comment une tâche « lint » simple peut utiliser la propriété this.filesSrc :

// Lit les fichiers spécifiés.
var files = this.filesSrc;
var errorCount = 0;
 
files.forEach(function(filepath) {
  if (!lint(grunt.file.read(filepath))) {
    errorCount++;
  }
});
 
// Met la tâche en échec si des erreurs sont loggées.
if (errorCount > 0) {
  return false;
}
 
// Autrement, imprime un message de succès.
grunt.log.ok('Fichiers lintés: ' + files.length);

Objet de configuration pour la target courante.

grunt.initConfig({
  exemple: {
    foo: [1, 2, 3],
    bar: 'Salut monde !',
    oque: { prop: 'value' }
  }
});
 
grunt.task.registerMultiTask('exemple', 'Un exemple de tâche…', function() {
  grunt.log.writeln(JSON.stringigy(this.data));
  // grunt exemple:foo  >> this.data = [1, 2, 3]
  // grunt exemple:bar  >> this.data = 'Salut monde !'
  // grunt exemple:oque >> this.data = { prop: 'value' }
});

Il est recommandé d'utiliser this.options, this.files et this.filesSrc au lieu de this.data, car leurs valeurs sont normalisées.