gruntfile-api

Api to programmatically modify a gruntfile

gruntfile-api

Api to programmatically modify your gruntfile

Install the module with: npm install gruntfile-api

var api = require('gruntfile-api'),
    fs = require('fs'),
    gruntfileData = fs.readFileSync('Gruntfile.js');
 
var output = api.init(gruntfileData)
    // change something 
    .toString();

Add a global variable declaration to the gruntfile. declarations get seamlessly integrated into existing declaration structures. Keep in mind that function calls like require('module') will be evaluated when passed to the function line this Use 'addGlobalDeclarationRaw` to prevent evaluation.

api.addGlobalDeclaration(identifier,value)

Type: string

Type: mixed

api.addGlobalDeclaration('defaultTasks',['jshint','uglify'])

adds the following code right before module.exports = function (grunt)

var defaultTasks = ['jshint','uglify'];

or

var varA = 'something',
    varB = 'something else',
    defaultTasks = ['jshint','uglify'];

Add a global variable declaration to the gruntfile. declarations get seamlessly integrated into existing declaration structures

api.addGlobalDeclarationRaw(identifier,value)

Type: string

Type: string

api.addGlobalDeclaration('path','require(\'path\')')

adds the following code right before module.exports = function (grunt)

var path = require('path');

Register grunt task with grunt.registerTask. when there already is a task registered with the same identifier. The tasks will get merged based on the mergeType argument unless this one is invalid or skip Merge will be done in one of the following ways depending on the mergeType:

  • registered task is array and task is array -> default merge
  • registered task is function and task is array -> merge will add grunt.task.run(tasks) to registered task body
  • registered task is array and task is function -> merge will add grunt.task.run(registered tasks) to task body
  • registered task is function and task is function -> merge will add task function body to registered task function body
api.registerTask(identifier,value)

Type: string

The task identifier

Type: array|function

The task which are invoked

Type: string can be one of the following: ['prepend','append','overwrite','skip'] Default: 'append'

How should tasks should be merged when there already is a task with the same identifier registered

api.registerTask('default',['jshint','uglify'])

adds the following code to the gruntfile

grunt.registerTask('default', ['jshint', 'uglify']);
api.registerTask('default',['jshint'],'prepend');

gruntfile before

grunt.registerTask('default', function(target) {
    grunt.task.run(['uglify']);
};

gruntfile after

grunt.registerTask('default', function(target) {
    grunt.task.run(['jshint']);
    grunt.task.run(['uglify']);
};

Insert Task configuration to the Gruntfile. Existing configurations should not be overwritten. That means, that the task target is added to the config if it already exists. Options will be added to the target configuration when the task already exists so that any existing configuration won't be messed up. Options that are already configured identically in the global task options will be dropped. Keep in mind that variable names or function calls will be evaluated when passed to the function line this When there's the need for variables or date objects use insertRawConfig

api.insertConfig(name,descriptor)

Type: string

The task identifier

Type: mixed

The task configuration

api.insertConfig('watch', {
    gruntfile: {
        options: {
            time: (new Date()).getTime()
        },
        files: 'Gruntfile.js',
        tasks: ['jshint:gruntfile']
    }
})

adds the following code to the gruntfile

watch: {
    gruntfile: {
        options: {
            time: 1394485101147
        },
        files: 'Gruntfile.js',
        tasks: ['jshint:gruntfile']
    }
}

or adds the watch target to an existing watch configuration

watch: {
    lib: {
        files: 'lib/**/*.js',
        tasks: ['jshint:lib', 'nodeunit']
    },
    gruntfile: {
        options: {
            time: 1394485101147
        },
        files: 'Gruntfile.js',
        tasks: ['jshint:gruntfile']
    }
}

Insert task configuration to the Gruntfile as String to prevent code evaluation

api.insertRawConfig(name,descriptor)

Type: string

The task identifier

Type: string

The task configuration as string.

api.insertRawConfig('watch', "{  js: { options: { time: (new Date()).getTime() }, files: MYPREVIOUSDECLAREDFILES, tasks: ['jshint'] } }")

adds the following code to the gruntfile

watch: {
    js: {
        options: {
            time: (new Date()).time()
        },
        files: MYPREVIOUSDECLAREDFILES,
        tasks: ['jshint']
    }
}

or appends it.

api.toString()

Invalid JSON Objects like variables or functions will added as String for information purpose

api.getJsonTasks()

Invalid JSON Objects like variables or functions will added as String for information purpose

api.hasConfig(identifier)

Type: string

The task identifier

Add loadNpmTasks call to Gruntfile. When load-grunt-tasks is active or the requested plugin is already loaded nothing will be added to the Gruntfile.

api.loadNpmTasks(pluginName)

Type: string

The plugin name

Invalid JSON Objects like variables or functions will added as String for information purpose

api.hasConfigProperty(identifier, property)

Type: string

The task identifier

Type: string|array

The property identifier

See examples/index.js

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

v0.0.1 - First very alpha!

v0.0.2 - Added some more functionality to the api

Copyright (c) 2014 Ben Zörb. Licensed under the MIT license.