gruntfile-api

Api to programmatically modify your gruntfile

Getting Started

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();

Documentation

Overview

• Add global declaration
• Add RAW global declaration
• Register task
• Insert task config
• Insert RAW task config
• Get the updated Gruntfile content
• Get JSON object with all configured tasks
• Test Gruntfile for task config
• loadNpmTask
• Test Gruntfile for property inside task config

Add global declaration

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)

parameter.identifier

Type: string

parameter.value

Type: mixed

example

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 RAW global declaration

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

api.addGlobalDeclarationRaw(identifier,value)

parameter.identifier

Type: string

parameter.value

Type: string

example

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

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

var path = require('path');

Register task

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)

parameter.identifier

Type: string

The task identifier

parameter.value

Type: array|function

The task which are invoked

parameter.mergeType

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

example

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

adds the following code to the gruntfile

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

merge example

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 config

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)

parameter.name

Type: string

The task identifier

parameter.descriptor

Type: mixed

The task configuration

example

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 RAW task config

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

api.insertRawConfig(name,descriptor)

parameter.name

Type: string

The task identifier

parameter.descriptor

Type: string

The task configuration as string.

example

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.

Get the updated Gruntfile content

api.toString()

Get JSON object with all configured tasks

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

api.getJsonTasks()

Test Gruntfile for task config

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

api.hasConfig(identifier)

parameter.identifier

Type: string

The task identifier

loadNpmTask

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)

parameter.pluginName

Type: string

The plugin name

Test Gruntfile for property inside task config

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

api.hasConfigProperty(identifier, property)

parameter.identifier

Type: string

The task identifier

parameter.property

Type: string|array

The property identifier

Examples

See examples/index.js

Contributing

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.

Release History

v0.0.1 - First very alpha!

v0.0.2 - Added some more functionality to the api

License

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