grunt-config-plus

Define package, description, aliases and task dependencies in an object/file per grunt task.

Version 1.0.x has a slightly different syntax compared to 0.1.x. I was getting tired to have to look up the format of a Gruntfile, so now the module makes it easier. Furthermore, I find that the builtin tasks are polluting the overview done by calling grunt, so I set them to invisible by default. For examples, you're reading the updated README.

This grunt configuration structure, like others, fetches its config from files. What I have not yet found so far is something that only loads the npm modules I need to run. Granted, grunt is fast after the first load, but I wanted grunt to always run as snappy as possible.

So here is grunt-config-plus. Define all your tasks fully within the scope of a single object. Refer tot those object with glob-paths, if you want. Create aliases for those tasks. List them, or hide them from the list. Print an explanation for your tasks. Json it, js it, whatever you fancy. It's so convenient.

Getting Started

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-config-plus --save-dev

Once the plugin is installed, create a Gruntfile.js in your root folder that looks like:

module.exports = require('grunt-config-plus')();

So if you wish to use it as part of a Gruntfile, you could also do:

module.exports = function(grunt) {
    require('grunt-config-plus')()(grunt);
}

The first function call is to optionally pass an config object, discussed below.

## The "grunt-config-plus" plugin

### Overview
Point to a directory where you hold all your config options:
```js
module.exports = require('grunt-config-plus')({
    init: 'grunt/*.*',
});

Now you can put all your task definitions in your specified folder.

A task definition

A task definition is a config file in js, json or yml format. If you use js, use module.exports.

Task definition parameters

A task definition may consist of:

• name: the grunt task name and grunt config name. Derived from the name of the config file.
• config: {Object} the configuration object that you would normally feed with grunt.initConfig under property 'name'
• description: {String} description of what this task does. Displayed when running grunt tasks or (default) grunt
• execute: {Function|Array} a function or array of task names that will be executed when this task is run.
• package: {String} a package the task(s) needs in order to run. What you would usually feed to grunt.loadNpmTasks
• dependencies: {Array} An array of task names this task depends on. If execute is an array of task names, it automatically appends dependencies.
• alias: {Array} one or multiple alternative task names for the task.
• visible: {Boolean} hides the task definition from the tasks list (see grunt tasks).

Task definition examples

A config file named browserify.json, producing the task grunt browserify and alias grunt b:

{
    "description": "Continuously builds index.js into bin/js-utils.js (dev)",
    "package": "grunt-browserify",
    "config": {
        "dev": {
            "files": {
                "bin/index.js": "index.js"
            },
            "options": {
                "watch": true,
                "keepAlive": true
            }
        }
    },
    "alias": "b"
}

A config file named buildBootstrap.js, producing the task grunt buildBootstrap not listed by grunt tasks:

module.exports = function(grunt, ROOT) {
    return {
        "description": "Creates custom bootstrap.js",
        "execute": function(param) {
            // entire function here
        },
        "visible": false
    }
};

A config file named install.json, producing the task grunt install and alias grunt i that run grunt bower, grunt less and grunt buildBootstrap:

{
    "description": "Installs all project dependencies",
    "execute": ["bower", "less", "buildBootstrap"],
    "alias": "i"
}

Config

The config is the optional object passed as parameter to grunt-config-plus.

Config properties

The config may have the following properties:

• init: {glob-path|Object} This parameter must yield an object containing all your task definitions. Interpreter searches again for glob-paths 1 level deep in the object.
• baseDir: {String} The path prepended to any glob-path used. Defaults to the cwd of Gruntfile.js.
• override: {glob-path|Object} Pass various overrides to affect the initialization process. All objects extend/overwrite the existing objects.
• init: {Object} Appends the init config after it has been assembled. This includes the default tasks.
• config: {Object} Appends the grunt config (derived from the 'config' properties of all your task definitions) after it has been assembled.
• dependencies: {String|Array} Appends the dependencies after they have been assembled. These tasks will always be loaded (not necessarily run). Pass * to load all tasks.
• style: {glob-path|Object} Customize the layout of the default tasks. Only one style property is possible. See grunt help for color styles.
• color: {String} common style
• descr: {String} style for descriptions only
• task: {String} style for task names
• indent: {String} character string used for indenting relative to the console.

Note that all results of a glob-path are automatically converted to an object, namespaced by file name.

Config default

{
    init: 'grunt/**/*.*',
    baseDir: process.cwd(),
    style: {
        color: 'yellow',
        indent: '  ',
        descr: 'cyan',
        task: 'bold'
    }
}

Config examples

Fetches config files from directory grunt-config relative to Gruntfile.js:

module.exports = require('grunt-config-plus')({
    init: 'grunt-config/*.*'
});

Show all builtin tasks:

module.exports = require('grunt-config-plus')({
    override: {
        init: {
            default: { visible: true },
            view: { visible: true },
            status: { visible: true },
            tasks: { visible: true },
            help: { visible: true }
        }
    }
});

Always loads all task definitions (and their dependencies and packages):

module.exports = require('grunt-config-plus')({
    override: {
        dependencies: '*'
    }
});

Tools

These tasks are added by default, and will automatically be overridden if you choose to set another task under that name.

• tasks, t: view all available tasks. Set as the default (run grunt).
• status: compare package.devDependencies with the packages defined in your config files.
• help, h: show tips, or, with other tasks, displays the description of the tasks
• view, v: view an object tree containing all loaded configs, as well as grunt itself. Optional path opens the (nested) property inside that object.

Release History

0.1.5: Prerelease 0.2.0: New notation, new defaults. 1.0.0: Oops that means by semver definition a new major number.