grunt-config-loader

A minimal grunt config loader that focuses on keeping a clean grunt file. Instead of having hundreds of lines of configs, you can move those into their own files and folders structured on your terms.

Installation

npm install grunt-config-loader

Usage

Using this utility is straight forward without much configuration.

First include the utility into your Gruntfile.

var GruntConfigLoader = require('grunt-config-loader');

The constructor takes two arguments, the grunt object and an options object. This object should be created within the Grunt export.

module.exports = function(grunt) {
  var gruntConfigLoader = new GruntConfigLoader(grunt, {});
};

Once your config loader has been created you can use few simple methods to load configs and have them auto inserted into the grunt config or load everything all at once. The loadAll leverages the same globing that grunt uses so you can filter the configs that will be laoded.

gruntConfigLoader.load('config');

or

gruntConfigLoader.loadAll();

All config files must maintain a specific form in order the config loader to load them in properly. The only guide line is that all configs must include a taskName.

modules.exports = {
  taskName: 'jshint',
  
  //config data can follow as usual.
  all: ['**/**.js', '!node_modules/**']
};

The config loader will insert that the config into a namespace provided by the taskName into the grunt config. if you do not specify a taskName an exception NoTaskNameException will be thrown. the taskName key can be changed in the options below.

You are allowed to use dot notation within task names to create sub namespaces. For example,

module.exports = {
  taskName: 'jshint.options',
  indent: 2
};

Would create the equivalence of:

jshint: {
 options: {
   indent: 2
 }
};

As of 0.2.0 you are able to export functions that will be evaluated on load passing the main grunt context, allowing you to be truly dynamic.

module.exports = function(grunt) {
  return {
  	taskName: 'jshint',
  	options: grunt.file.readJSON('some/other/file')
  };
};

Unless overridden you are also allowed to combine fragments by simply including the same namespace in two or more different configs. This allows you to be as granular as you wish.

Because the load mechanism leverages nodes require, you are allowed to use JSON files as well.

Options

There are several options that can be configured that controls were and how a config or a set of configs is loaded.

cwd: {String}

A string that specifies were configs will be relative to when loading. the cwd is set to 'tasks' by default. cwd will always be relative to process.cwd().

match: {String | Array}

A minmatch parameter this is only used in loadAll. This parameter specifies how to search and what to search for. All files that are globed will try to be loaded. by default its any javascript file recursively.

taskName: {String}

A string that allows you to specify a key that will be used to determine which namespace to load the config into. Its default is 'taskName'.

overWrite {String | Boolean | Array}

This parameter allows a script to determine how namespace collisions are handled. A namespace collision occurs when two or more configs try to assign themselves under the same taskName. Most of the time this is something that is desired especially when loaded a bunch of smaller fragments. The loader by default will merge any conflict namespaces it finds. However if for some reason this needs to be overwritten, the overWrite parameter can be set to true and namespaces will be simple overwritten. The options allows for finer control as well, you can specify a single name and it will merge all but the namespace specified. You can also pass an Array of names to force overwriting.

any option that can be used with grunt.file.expand can also be used.

strict

If this is set to false, an exception will no longer be thrown when trying load files with unassigned tasks. Instead of using this, a better solution would be to simply create a dedicated configs folder and use cwd.

Methods

load({!(String|Array)})

Will attempt to load a single config file relative to cwd. It will throw an exception if the file doesnt exist. It will also throw an exception if there is no defined task with strict enabled.

loadAll()

Will attempt to load all configuration files following the rules set in options. Will through the same exceptions as load.

getOptions()

Returns a list of resolved options that are being used by the instance.

export()

Returns the current state of grunt config.