Awesome
gruntfile-gtx
Turbo, spoilers and a sunroof for your Gruntfile.
Grunt enhancement to make gruntfile task management more dynamic and powerful. Handle demanding setups while keeping your Gruntfile shiny and DRY.
Features
- Use macros to generate chains of related (semi-anonymous) plugin task instances.
- Use tags to group and select similar targets.
- Create new aliases by filtering tasks on various fields.
- Transparently streamline gruntfile api a little.
Macros are powerful to define chains of targets for different plugins that together define a blueprint for build-sub-process. Create different instances that share or change parameters like identifiers, (partial) paths.
API Change
Per v0.1.0
the API was updated. The old docs can be found here
Usage
Check the Gruntfile for practical dogfooding and browse the tests for some more options.
Example
module.exports = function (grunt) {
// get the gtx instance
var gtx = require('gruntfile-gtx').wrap(grunt);
Load some plugins:
gtx.loadNpm(
'myPlugin',
'myOtherPlugin'
);
//classic array
gtx.loadNpm([
'myPlugin',
'myOtherPlugin'
]);
// folder
gtx.loadTasks('./tasks');
// alternately load automatically (from ./tasks and ./node_modules)
gtx.loadAuto();
Build the grunt config like the regular structure:
gtx.config({
// read and blend objects
pkg: gtx.readJSON('package.json', {title: 'foo'}, './conf/overwrite.json'),
myPlugin: {
options: {
//..
},
main: {
src: ['./files/main/*.js']
}
},
myOtherPlugin: {
main: {
src: ['./files/dev/*.js']
}
}
});
// ... but split over multiple statements
gtx.config({
myPlugin: {
dev: {
src: ['./files/dev/*.js']
}
}
});
// or directly set config objects
gtx.configFor('myPlugin', 'beta', {
src: ['./files/beta/*.js']
});
Define tasks:
// define a simple task
gtx.call('say', function() {
grunt.log.writeln('hello!');
});
// define a multi-task
gtx.multi('alpha_multi', function() {
var options = this.options({
//..
});
grunt.log.writeln('hello!');
});
Run tasks:
// named serial
gtx.alias('many', ['one', 'two', 'three']);
// named concurrent (max cpu cores)
gtx.concurrent('many', ['one', 'two', 'three']);
Generate a unique name for a configuration (this is the basis for the macro feature)
var name = gtx.configFor('myPlugin', {
src: ['./files/gamma/*.js']
});
// do creative stuff by generating tasks (go wild here)
gtx.alias('bulk_run', ['one', 'two', 'three'].map(function (name) {
return gtx.configFor('myPlugin', {
src: ['./files/' + name + '.js']
});
}));
// generated tasks from parallel() to run concurrently
gtx.alias('many', ['one', gtx.parallel('two', 'three')]);
// generated tasks from serial()
gtx.alias('more', ['one',
gtx.parallel(
gtx.serial('two', 'three'),
gtx.serial('four', 'five'))
)
]);
This example is lifted from the gruntfile of TSD and shows a macro to compile and run separated 'test modules'. These can also be run concurrently to cut-down on overall test-duration for IO heavy topics.
Note how the macro uses a few plugins to setup and run: it would be a hassle to maintain these modules in a regular gruntfile but it is easy when using a macro to build the instance:
gtx.define('module_tester', function (macro, id) {
// the macro object is a context with helpers to assemble a new instance named 'id'
// let's use the instance id to build a shared path
var testPath = 'test/modules/' + id + '/';
// use grunt-contrib-clean to remove old test output
macro.add('clean', [testPath + 'tmp/**/*']);
// run a regular task
macro.run('myPlugin:dev');
// use grunt-ts to compile the TypeScript test cases
macro.add('ts', {
options: {},
src: [testPath + 'src/**/*.ts'],
out: testPath + 'tmp/' + id + '.test.js'
});
// use grunt-tslint
macro.add('tslint', {
src: [testPath + 'src/**/*.ts']
});
// optionally spawn a grunt-contrib-connect
if (macro.getParam('http', 0) > 0) {
macro.add('connect', {
options: {
port: macro.getParam('http'),
base: testPath + 'www/'
}
});
//tag for easy retrieval
macro.tag('http');
}
// run grunt-mocha-test on the compiled test cases
macro.add('mochaTest', {
options: {
timeout: macro.getParam('timeout', 2000)
},
src: [testPath + 'tmp/**/*.test.js']
});
}, {
// optionally run parallel using grunt-concurrent (for now only from gtx-type)
concurrent: 4
});
Use the macro to make many similar instances:
// use the macro to make many instances
gtx.create('git', 'module_tester', null, 'lib');
gtx.create('tsd', 'module_tester', {timeout: 10000}, 'lib,core');
gtx.create('http', 'module_tester', {
timeout: 20000,
http: 8080
}, 'lib');
// bulk
gtx.create('basic,remote,local', 'module_tester');
gtx.create(['basic','remote','local'], 'module_tester');
Mix functions and id's:
// mix calls in alias
gtx.alias('mix', ['alpha:one', 'bravo:two', function() {
grunt.log.writeln('roger');
}, 'charlie', function() {
grunt.log.writeln('roger');
}]);
Finish up:
// let's make an alias to run all instances as your $ grunt test
gtx.alias('test', 'gtx-type:module_tester');
// alias is short-cut for grunt.registerTask();
gtx.alias('default', ['test']);
// compile and send to grunt.initConfig()
gtx.finalise();
};
To run these macro instances:
$ grunt -h
$ grunt gtx:git
$ grunt gtx-group:core
$ grunt gtx-group:http
$ grunt gtx-type:module_tester
// bonus: clean all
$ grunt clean
Additional examples:
- Complex example from mocha-unfunk-reporter uses a macro to setup a CLI output bulk tester (this is also a warning about power and responsibility).
Info
- Your gruntfile is still a regular gruntfile to run by
grunt-cli
.- Use the
grunt -h
command to view the generated tasks. - Main difference is to import and apply
gruntfile-gtx
on start if the Gruntfile. - Call
gtx.finalise()
at the end of the file to generate the config and apply aliases.
- Use the
- Generated aliases are prefixed with
gtx
, likegtx-select:myAlias
orgtx-group:dev
.- They run like any task created by
grunt.registerTask()
.
- They run like any task created by
- The extra API sugar like
gtx.loadNpm()
is optional, but is generally DRY-er then the regular versions. - String input uses a form of expansion and iteration where applicable.
- Split strings on separators to array:
gtx.alias('name', 'one, two, three')
- Nested arrays are flattened and the content split:
gtx.alias('name', [['aa','bb'], 'cc', ['dd, ee'],'ff,gg,hh'])
- Where grunt methods accept a single string the alias will iterate:
gtx.loadNpm([..])
- Split strings on separators to array:
- Gruntfile-gtx was grown organically: no gold-plating but some edges made shiny from wear.
Future
There a lot of ideas for this floating around for this, from auto-dependency chains and non-repeating macro util tasks, to globbing helpers to generate macro instances and flows adapting to custom cli parameters or env variables. Also it would be cool to interface with (Yeoman) generators for easy instancing of build sub modules.
Most of these wait until Grunt reaches 0.5.0
which solve some of the original problems.
API
See above usage examples and look at the Gruntfile and the tests for more usage.
Release History
See the CHANGELOG.
Contributing
Contributions are welcome (idiomatic, clean etc) but best to post a proposal in the Issues before making big changes.
License
Copyright (c) 2013-2018 Bart van der Schoor
Licensed under the MIT license.