ixisio / grunt-modernizr

Build out a lean, mean Modernizr machine.

grunt-modernizr

tl;dr: grunt-modernizr sifts through your project files, gathers up your references to Modernizr tests and outputs a lean, mean Modernizr machine.

grunt-modernizr is a Modernizr builder for your project. It is based on the Modernizr team's Modulizr tool.

This highly configurable task allows you to configure and export a custom Modernizr build. Use Modernizr's annotated source for development, and let this tool worry about optimization.

When you're ready to build, grunt-modernizr will crawl your project for Modernizr test references and save out a minified, uglified, customized version using only the tests you've used in your JavaScript or (S)CSS.

Getting Started

Install this grunt plugin next to your project's grunt.js gruntfile with:

npm install grunt-modernizr --save-dev

Then add this line to your project's grunt.js gruntfile:

grunt.loadNpmTasks("grunt-modernizr");

Documentation

Command Line

Run the task with grunt modernizr:dist.

Cache Busting

Bust the cache of locally downloaded files by running grunt modernizr:dist:bust

Config Options

Add a modernizr config object to your Gruntfile.js file. The task supports multiple targets:

modernizr: {

	dist: {
		// [REQUIRED] Path to the build you're using for development.
		"devFile" : "lib/modernizr-dev.js",

		// Path to save out the built file.
		"outputFile" : "build/modernizr-custom.js",

		// Based on default settings on http://modernizr.com/download/
		"extra" : {
			"shiv" : true,
			"printshiv" : false,
			"load" : true,
			"mq" : false,
			"cssclasses" : true
		},

		// Based on default settings on http://modernizr.com/download/
		"extensibility" : {
			"addtest" : false,
			"prefixed" : false,
			"teststyles" : false,
			"testprops" : false,
			"testallprops" : false,
			"hasevents" : false,
			"prefixes" : false,
			"domprefixes" : false,
			"cssclassprefix": ""
		},

		// By default, source is uglified before saving
		"uglify" : true,

		// Define any tests you want to implicitly include.
		"tests" : [],

		// By default, this task will crawl your project for references to Modernizr tests.
		// Set to false to disable.
		"parseFiles" : true,

		// When parseFiles = true, this task will crawl all *.js, *.css, *.scss and *.sass files,
		// except files that are in node_modules/.
		// You can override this by defining a "files" array below.
		// "files" : {
			// "src": []
		// },

		// This handler will be passed an array of all the test names passed to the Modernizr API, and will run after the API call has returned
		// "handler": function (tests) {},

		// When parseFiles = true, matchCommunityTests = true will attempt to
		// match user-contributed tests.
		"matchCommunityTests" : false,

		// Have custom Modernizr tests? Add paths to their location here.
		"customTests" : []
	}

}

Required

devFile (String)

Path to the local build file you're using for development. This parameter is needed so grunt-modernizr can skip your dev file when traversing your project to avoid triggering false positives. If you're using a remote file for development, set this option to remote.

Optional

outputFile (String)

Path to save the customized Modernizr build. It defaults to lib/modernizr-custom.js.

extra (Object)

An object of extra configuration options. Check the extra section on modernizr.com/download for complete options. Defaults are as they appear on the official site.

extensibility (Object)

An object of extensibility options. Check the section on modernizr.com/download for complete options. Defaults are as they appear on the official site.

uglify (Boolean)

By default, the source is uglified before save. Set to false to disable.

tests (Array)

Define any tests you want to implicitly include. Test names are lowercased, separated by underscores (if needed). Check out the full set of test options here.

parseFiles (Boolean)

By default, this task will crawl your project for references to Modernizr tests. Set to false to disable.

files.src (Array)

When parseFiles = true, this task will crawl all *.js, *.css, *.scss and *.sass files. You can override this by defining a custom files.src array. The object supports all minimatch options.

handler (Function)

This handler will be passed an array of all the test names passed to the Modernizr API, and will run after the API call has returned. Optionally, if the function is asynchronous then grunt's asynchronous done callback will be passed into this handler as the second parameter and must be called manually in order to complete the grunt-modernizr task

// synchronous use - grunt-modernizr will exit anyway
handler: function (tests) {
	// synchronous code
}

// asynchronous use - grunt-modernizr will not exit until done() is called
handler: function (tests, done) {
	// asynchronous code
	done();
}

matchCommunityTests (Boolean)

When parseFiles = true, setting this boolean to true will attempt to match user-contributed tests. Check out the full set of community tests here

customTests (Array)

Have custom Modernizr tests? Add paths to their location here. The object supports all minimatch options.

excludeFiles (Array)

Files added here will be excluded when looking for Modernizr refs. The object supports all minimatch options.

License

Copyright (c) 2012 Richard Herrera Licensed under the MIT license.