1.4.1 • Public • Published



    Version Build status

    Support for pipeline execution of grunt tasks.
    CLI operation is not required to use.


    Install with npm:

    npm install grunt-runner

    API - simplest running

    // Let's run the regist(Multi)Task()-ed tasks 'concat' and 'uglify'
    require('grunt-runner')(['concat', 'uglify']);


    var gr = require('grunt-runner');
      pkg: { name:"grunt-runner-test" },
      concat: { /*(concat's config)*/ },
      uglify: { /*(uglify's config)*/ }
      'npm:grunt-contrib-concat'  // grunt.loadNpmTasks('grunt-contrib-concat')
    , 'npm:grunt-contrib-uglify'  // grunt.loadNpmTasks('grunt-contrib-uglify')
    , 'concat', 'uglify']);

    API - runs and pipe tasks under "tasks" directory

    assume that directory exists just below executing script file

      runner = require('grunt-runner')([rootdir][,taskdir][,comconf])

    ,or use alias

      runner = require('grunt-runner').run([rootdir][,taskdir][,comconf])

    ,then debug mode

      gr = require('grunt-runner'); gr.set('debug', true); // use 'trace' for more detail.
      runner =[rootdir][,taskdir][,comconf])


    rootdir (String) process.cwd() optional
    The working place for this runner. process.chdir(rootdir) is performed before begin.

    taskdir (String) 'tasks' optional
    The directory where tasks used in for this runner.
    Note that if you want to specify taskdir but not specify rootdir, please set null for the first argument.

    comconf (Object) {} optional
    The configuration for each tasks.
    e.g. { "taskname": { (grunt task configuration) } }


    A runner is an instance of EventEmitter.

    type finish
    Emit when end for each task.

    runner.on('finish', function(taskname) { ... })  

    type error
    Emit when error occurs.
    If no handler is binded, the error will be thrown as you know.

    runner.on('error', function(e, taskstat) { ... })  

    type end
    Emit when all in "taskList" are ended.

    runner.on('end', function() { ... })  

    type (taskname).(eventname) All of grunt.event.emit event will pass runner as this each type.
    When you executing (taskname):(tag) task, :(tag) will be ignored.
    In taskname "hoge"'s Gruntfile.js

    grunt.event.emit('ok', 1, 2, 3);

    You can catch the event by runner.on

    runner.on('hoge.ok', function() { console.log(arguments) }) // [1, 2, 3]

    You can also catch this event for type data.

    runner.on('data', function(d) { console.log(d) }) // ['hoge.ok', 1, 2, 3]

    - example for running configuration

    Default reading target: package.json

      "name": "grunt-runner-test",
      "version": "1.0.0",
      "taskList": ["run"],
      "configure": {

    You can change the target_file_name via argv or specify in taskdir

    node main.js --config=package-alias.json


    require('grunt-runner').run(rootdir, 'package-alias.json')

    In taskdir, you can specify task_directory and target_file_name, both or either with using comma ",".
    e.g. taskgroup.json,tasks, taskgroup.json, tasks
    The value will be treated as a target_file_name when .json is found at the last of the value.

    This file is not required. If not provide (and the "taskList" is not provided, )
    (1) Tasks are listed up by the directory list in taskdir.
    (2) If tasks are listed, run the tasks.
    (3) If no task is discovered, grunt.start() is simply called. Then tasks which are already grunt.regist(Multi)Task()-ed are started.

    before example for Gruntfile.js, note that underscore is included.

    This object is extended for running tasks.
    see: lib/task-util.js

    var _ = require('grunt-runner')._;

    - example for Gruntfile.js

    in this case deploy in "tasks/run" directory

    module.exports = function(grunt) {
      grunt.registerTask('run', 'test for grunt-runner', function() {

    - if you want add tasks more easily, use utilities

    var path = require('path'), fs = require('fs'), _ = require('grunt-runner')._;
    var taskname = _.taskname(__dirname); // run
    module.exports = function(grunt) {
      var tmes = 'Grunt Runner test: ' + taskname;
      grunt.registerTask(taskname, tmes, _.caught(function() {
        gruntRunnerTest(grunt, _.mixedConfigure(grunt, taskname), this);
    function gruntRunnerTest(grunt, conf, gtask) {
      var line = [], done = gtask.async();
      line.push(function() {
        grunt.log.writeln('[' + + '] done.'), done();

    - of course, available "Grunt Plugins" in Gruntfile.js!

    The most comfortable way to construct a task.

    module.exports = function(grunt) {
      var bann = '/*! <%= %>'
        + ' <%="dd-mm-yyyy") %> */\n';
      grunt.config.set('concat', {
        options: {
          separator: ";"
        dist: {
          src: ["src/*.js"],
          dest: "dist/<%= %>.js"
      grunt.config.set('uglify', {
        options: {
          banner: bann
        dist: {
          files: {
            'dist/<%= %>.min.js': ['<%= concat.dist.dest %>']
      grunt.registerTask('concat-uglify', ['concat', 'uglify']);

    - task config can be pre-given not only via package.json but also as an execute option

      "name": "grunt-runner-test",
      "version": "1.0.0",
      "taskList": ["run"],
      "configure": {
        "concat": {
          "banner": "/*! <%= %> <%=\"dd-mm-yyyy\") %> */\\n"

    same configuration can be given at the time of run

      pkg: {
        name: 'grunt-runner-test',
        version: '1.0.0',
        taskList: ['run']
      concat: {
        banner: '/*! <%= %> <%="dd-mm-yyyy") %> */\n'

    then, Gruntfile.js will be very smart.

    var taskname = require('grunt-runner')._.taskname(__dirname); // get directory name
    module.exports = function(grunt) {
      grunt.registerTask(taskname, ['concat', 'uglify']);


    I want to request some fixing of grunt himself functionally but not yet.
    So that please use grunt-runner with paying some attention listed below:

    • If same name is defined recursively, task is not ended forever
    • "" method is evil because this method is disappear the error thrown. Please throw error simply if you want to finish the task.
    • "node_modules" requires at the root of your project directory for loadNpmTasks

    If you know the way to avoid them by the function (or option) of grunt, let me know, please.


    npm i grunt-runner

    DownloadsWeekly Downloads






    Last publish


    • ystskm