grunt-thrall

Grunt task orchestrator/warchief

"The beginning of wisdom is the statement 'I do not know.' The person who cannot make that statement is one who will never learn anything. And I have prided myself on my ability to learn." - Thrall in Cycle of Hatred, page 77

Why?

When a project uses lots of Grunt Tasks, the Gruntfile.js tends to get really messy and hard to maintain.

With grunt-angular-toolbox, we tried to extract this complexity into a toolbox that handles all grunt related things for a main project.

This works fine, but the toolbox itself was still spaghetti-code-ish and hard to understand and maintain for most users.

Thrall contains all orchestration logic and is 100% test covered. This allows consuming packages to focus on task definition without having to worry to much about configuration loading and option handling.

Usage

Install the module:

npm install grunt-thrall --save-dev

// gruntfile.js
module.exports = function(grunt) {
    var thrall = require('grunt-thrall');
    
    thrall.init({
        /* see config */	
    });	
};

This can be used for any project or grunt plugin. See:

• Example project
• Grunt Plugin

API

thrall.init(config)

• Load all grunt plugins, specified in the projects package.json (heavily inspired by load-grunt-tasks)
• merge defaults, provided in config with settings is grunt.config
• Search for custom tasks, specified in the tasks/ directory
• Dynamically load configuration for grunt plugins used by those tasks from config/ directory

Config

Required string: dir

thrall.init({dir: __dirname + 'myTasks' /* ,... */ });

The basic directory for custom tasks and grunt plugin configuration.

Expects subdir tasks/ for custom tasks and config/ for grunt plugin configuration to be present.

Required string: basePath

thrall.init({basePath: __dirname /* ,... */ });

The projects base path.

Used to findup node_modules/grunt-*/tasks/* when auto-loading grunt plugins.

Required object: grunt

thrall.init({grunt: grunt /* ,... */ });

The currently running grunt instance.

string: name

thrall.init({name: 'myProject' /* ,... */ });

Defaults to config.pkg.name project name from package.json

This is also the key for custom configuration that is merged with the defaults

// pseudo-code
var config = _.merge(config.getDefaults(), grunt.config(config.name));

boolean: loadDevDependencies

thrall.init({loadDevDependencies: false /* ,... */ });

Default: true

Whether or not to include devDependencies from package.json when auto-loading grunt plugins.

boolean: loadDependencies

thrall.init({loadDependencies: true /* ,... */ });

Default: false

Whether or not to include dependencies from package.json when auto-loading grunt plugins.

object: module

thrall.init({
    module: {
        myHelper: ['factory', require('./helpers/myHelper')]
    }
    /* ,... */ 
});

Default: {}

Task definitions, grunt plugin configurations and getDefaults are being invoked using node-di providing basic node modules.

When you need a custom helper, it can be registered here.

See DI for further informations.

function: getDefaults

thrall.init({
    getDefaults: function(/* di here */) {
        return {
            foo: 'bar'
        }
    }
    /* ,... */ 
});

Default configuration will be merged and be available as grunt.config(config.name).

Task Factories

every file in config.dir/tasks/ is expected to export a factory function, returning a task definition object. The name will be generated by the path relative to the tasks dir.

Factories are being invoked using node-di, see DI for further informations.

Naming

// tasks/foo/bar.js
module.exports = function(/* di here */) {
    return {};
};

will register task foo:bar that, when can be called with grunt foo:bar and does nothing.

string/array: description

module.exports = function() {
    return {
        description: [
            'this is the bar tasks',
            'it will foo.'
        ]
        /* ... */
    };
};

Task description, which is displayed by grunt --help. Arrays will be .join('\n')-ed.

array: run

Subtasks to run by this task.

// tasks/foo/bar.js
module.exports = function() {
    return {
        /* ... */
        run: [
            'jshint:src',
            'mochaTest'
        ]
    };
};

Will load for grunt plugin configurations from config/jshint/src.js and config/mochaTest.js (see Configuration Factories) and execute both subtasks when grunt foo:bar is called.

runIf blocks

A runIf block can add tasks to the cue based on grunt configuration.

module.exports = function() {
    return {
        /* ... */
        run: [
            'other:task',
            {
                if: 'coverage.enabled',
                task: ['coverage']
            },
            {
                if: [
                    (null != 1),
                    'foo.bar'
                ],
                task: 'report',
                else: 'say:goodbye'
            }
        ]
    };
};

In the above example:

• the coverage task will only run when grunt.config.get('coverage.enabled') returns a truthy value.
• the report task will run when grunt.config.get('foo.bar') is truthy, (and null != 1 which is of cause true, too)
• when grunt.config.get('foo.bar') is falsy the say:goodbye task runs instead

All expressions and config values in an if-array need to be true in order to run the task. There is no OR operator or !-negation.

This works well with options.

object: options

Map CLI options, environment variables and grunt modifiers to grunt config.

// tasks/foo/bar.js
module.exports = function() {
    return {
        /* ... */
        options: {
            coverage: 'coverage.enabled'
        }
    };
};

grunt foo:bar --coverage will set the grunt.config('coverage.enabled') to true.

// tasks/foo/bar.js
module.exports = function() {
    return {
        /* ... */
        options: {
            'demo-port': {
                env: 'DEMO_PORT',
                alias: 'port',
                key: 'foo.demoPort'
            }
        }
    };
};

either of

• grunt foo:bar --demo-port=7000
• grunt foo:bar --demo=7000
• DEMO_PORT=7000 grunt foo:bar

will set the grunt.config('foo.demoPort') to 7000.

// tasks/foo/bar.js
module.exports = function() {
    return {
        /* ... */
        options: {
            coverage: {
                grunt: ':coverage',
                key: 'coverage.enabled'
            }
        }
    };
};

grunt foo:bar:coverage will set grunt.config('coverage.enabled') to true.

function: runFilter

Filter that may manipulate the tasks cue before execution.

// tasks/foo/bar.js
module.exports = function() {
    return {
        /* ... */
        run: ['foo', 'bar'],
        runFilter: function(tasks, args) {
            if (args[0] === 'baz') {
                tasks.shift();
            }
            return tasks;
        }
    };
};

In this case, when grunt foo:bar:baz is called, only the foo subtask will run.

Configuration Factories

every file in config.dir/config/ is expected to export a factory function, returning a configuration object. The name has to match the path that this configuration will be placed at, in the grunt config.

Factories are being invoked using node-di, see DI for further informations.

// config/jshint/src.js
module.exports = function(/* di here */) {
    return {
        options: {
            ignores: ['**/*.coffee'],
            jshintrc: true,
        },
        src: [
            '<%= my.src.files.js %>'
        ]
    };
};

This is similar to the following standard configuration, only that it's split in to a lot of small files, with is more easy to maintain for big projects.

grunt.initConfig({
    jshint: {
        src: {
            options: {
                ignores: ['**/*.coffee'],
                jshintrc: true,
            },
            src: [
                '<%= my.src.files.js %>'
            ]
        }
    }
});

DI

getDefaults, Task Factories and Configuration Factories are being invoked with a node-di module, providing the following services:

• _: lodash
• cliOptions: CLI Options using minimist
• del: del
• findupSync: node-findup-sync
• fs: node module
• getobject: node-getobject
• glob: node-glob
• grunt: currently running grunt instance
• mkdirp: node-mkdirp
• path: node module
• merged: (getDefaults ONLY) See merged callback
• name: (Task Factories ONLY) name of the task
• rootTask: (Task Factories ONLY) the name of the task that has actually been called

merged callback

/* ... */
getDefaults: function(merged) {
    merged(function(mergedConfig) {
        mergedConfig.foo = 'baz';
    });
    return {foo: 'bar'};
}

MIT License