Grunt-init is a scaffolding tool used to automate project creation. It will build an entire directory structure based on the current environment and the answers to a few questions. The exact files and contents created depend on the template chosen along with the answers to the questions asked.
Note: This standalone utility used to be built-in to Grunt as the "init" task. See the Grunt Upgrading from 0.3 to 0.4 guide for more information about this change.
In order to use grunt-init, you'll want to install it globally.
npm install -g grunt-initThis will put the grunt-init command in your system path, allowing it to be run from anywhere.
Notes: You may need to use sudo or run your command shell as Administrator to do this.
- Get program help and a listing of available templates with
grunt-init --help - Create a project based around an available template with
grunt-init TEMPLATE - Create a project based around a arbitrarily-located template with
grunt-init /path/to/TEMPLATE
Note that most templates generate their files in the current directory, so be sure to change to a new directory first if you don't want to overwrite existing files.
Once templates are installed into your ~/.grunt-init/ directory (%USERPROFILE%\.grunt-init\ on Windows) they will be available for use via grunt-init. It's recommended that you use git to clone a template into that directory. For example, the grunt-init-jquery template can be installed like so:
git clone https://github.com/gruntjs/grunt-init-jquery.git ~/.grunt-init/jquery
Note: if you want to make the template available locally as "foobarbaz" you could specify ~/.grunt-init/foobarbaz while cloning. Grunt-init will use the actual template directory name as it exists inside of the ~/.grunt-init/ directory.
A few grunt-init templates are maintained officially:
- grunt-init-commonjs - Create a commonjs module, including Nodeunit unit tests. (sample "generated" repo | creation transcript)
- grunt-init-gruntfile - Create a basic Gruntfile. (sample "generated" repo | creation transcript)
- grunt-init-gruntplugin - Create a Grunt plugin, including Nodeunit unit tests. (sample "generated" repo | creation transcript)
- grunt-init-jquery - Create a jQuery plugin, including QUnit unit tests. (sample "generated" repo | creation transcript)
- grunt-init-node - Create a Node.js module, including Nodeunit unit tests. (sample "generated" repo | creation transcript)
You can create and use custom templates. Your template must follow the same structure as the aforementioned templates.
A sample template named my-template would follow this general file structure:
my-template/template.js- the main template file.my-template/rename.json- template-specific rename rules, processed as templates.my-template/root/- files to be copied into the target location.
Assuming these files exist at /path/to/my-template, the command grunt-init /path/to/my-template would be used to process the template. Multiple uniquely-named templates may exist in the same directory.
Additionally, if you place this custom template in your ~/.grunt-init/ directory (%USERPROFILE%\.grunt-init\ on Windows) it will be automatically available to be used with just grunt-init my-template.
As long as a template uses the init.filesToCopy and init.copyAndProcess methods, any files in the root/ subdirectory will be copied to the current directory when the init template is run.
Note that all copied files will be processed as templates, with any {% %} template being processed against the collected props data object, unless the noProcess option is set. See the jquery template for an example.
The rename.json describes sourcepath to destpath rename mappings. The sourcepath must be the path of the file-to-be-copied relative to the root/ folder, but the destpath value can contain {% %} templates, describing what the destination path will be.
If false is specified as a destpath the file will not be copied. Also, glob patterns are supported for srcpath.
Each init prompt either has a default value hard-coded or it looks at the current environment to attempt to determine that default value. If you want to override a particular prompt's default value, you can do so in the optional OS X or Linux ~/.grunt-init/defaults.json or Windows %USERPROFILE%\.grunt-init\defaults.json file.
For example, my defaults.json file looks like this, because I want to use a slightly different name than the default name, I want to exclude my email address, and I want to specify an author url automatically.
{
"author_name": "\"Cowboy\" Ben Alman",
"author_email": "none",
"author_url": "http://benalman.com/"
}Note: until all the built-in prompts have been documented, you can find their names and default values in the source code.
This brief template description will be displayed along with the template name when the user runs grunt init or grunt-init to display a list of all available init templates.
exports.description = descriptionString;If specified, this optional extended description will be displayed before any prompts are displayed. This is a good place to give the user a little help explaining naming conventions, which prompts may be required or optional, etc.
exports.notes = notesString;If this optional (but recommended) wildcard pattern or array of wildcard patterns is matched, Grunt will abort with a warning that the user can override with --force. This is very useful in cases where the init template could potentially override existing files.
exports.warnOn = wildcardPattern;While the most common value will be '*', matching any file or directory, the minimatch wildcard pattern syntax used allows for a lot of flexibility. For example:
exports.warnOn = 'Gruntfile.js'; // Warn on a Gruntfile.js file.
exports.warnOn = '*.js'; // Warn on any .js file.
exports.warnOn = '*'; // Warn on any non-dotfile or non-dotdir.
exports.warnOn = '.*'; // Warn on any dotfile or dotdir.
exports.warnOn = '{.*,*}'; // Warn on any file or dir (dot or non-dot).
exports.warnOn = '!*/**'; // Warn on any file (ignoring dirs).
exports.warnOn = '*.{png,gif,jpg}'; // Warn on any image file.
// This is another way of writing the last example.
exports.warnOn = ['*.png', '*.gif', '*.jpg'];While the exports properties are defined outside this function, all the actual init code is specified inside. Three arguments are passed into this function. The grunt argument is a reference to grunt, containing all the grunt methods and libs. The init argument is an object containing methods and properties specific to this init template. The done argument is a function that must be called when the init template is done executing.
exports.template = function(grunt, init, done) {
// See the "Inside an init template" section.
};Add properly-named license files to the files object.
var files = {};
var licenses = ['MIT'];
init.addLicenseFiles(files, licenses);
// files === {'LICENSE-MIT': 'licenses/LICENSE-MIT'}Return an array of available licenses.
var licenses = init.availableLicenses();
// licenses === [ 'Apache-2.0', 'GPL-2.0', 'MIT', 'MPL-2.0' ]Given an absolute or relative source path, and an optional relative destination path, copy a file, optionally processing it through the passed callback.
init.copy(srcpath[, destpath], options)Iterate over all files in the passed object, copying the source file to the destination, processing the contents.
init.copyAndProcess(files, props[, options])User-specified default init values from defaults.json.
init.defaultsAbsolute destination file path.
init.destpath()Same as grunt.file.expand.
Return a unique array of all file or directory paths that match the given wildcard pattern(s). This method accepts either comma separated wildcard patterns or an array of wildcard patterns. Paths matching patterns that begin with ! will be excluded from the returned array. Patterns are processed in order, so inclusion and exclusion order is significant.
init.expand([options, ] patterns)Return an object containing files to copy with their absolute source path and relative destination path, renamed (or omitted) according to rules in rename.json (if it exists).
var files = init.filesToCopy(props);
/* files === { '.gitignore': 'template/root/.gitignore',
'.jshintrc': 'template/root/.jshintrc',
'Gruntfile.js': 'template/root/Gruntfile.js',
'README.md': 'template/root/README.md',
'test/test_test.js': 'template/root/test/name_test.js' } */Get a single task file path.
init.getFile(filepath[, ...])Returns an object of all the available templates.
init.getTemplates()Initialize the directories to search for init templates. template is the
location of a template. Will also include ~/.grunt-init/ and the core init
tasks within grunt-init.
init.initSearchDirs([filename])Start up the process to begin prompting for input.
init.process(options, prompts, done)init.process({}, [
// Prompt for these values
init.prompt('name'),
init.prompt('description'),
init.prompt('version')
], function(err, props) {
// All finished, do something with the properties
});Prompt a user for a value.
init.prompt(name[, default])An object of all the prompts.
var prompts = init.prompts;Read JSON defaults from task files (if they exist), merging them into one data object.
init.readDefaults(filepath[, ...])The rename rules for the template.
var renames = init.renames;
// renames === { 'test/name_test.js': 'test/{%= name %}_test.js' }An array of directories to search for templates in.
var dirs = init.searchDirs;
/* dirs === [ '/Users/shama/.grunt-init',
'/usr/local/lib/node_modules/grunt-init/templates' ] */Search init template paths for filename and return an absolute path.
init.srcpath(filepath[, ...])Returns the absolute path to the user's template directory.
var dir = init.userDir();
// dir === '/Users/shama/.grunt-init'Save a package.json file in the destination directory. The callback can be used to post-process properties to add/remove/whatever.
init.writePackageJSON(filename, props[, callback])Author's email address to use in the package.json. Will attempt to find a default value from the user's git config.
Author's full name to use in the package.json and copyright notices. Will attempt to find a default value from the user's git config.
A public URL to the author's website to use in the package.json.
A relative path from the project root for a cli script.
A public URL to the project's issues tracker. Will default to the github issue tracker if the project has a github repository.
A description of the project. Used in the package.json and README files.
A valid semantic version range descriptor of Grunt the project requires.
A public URL to the project's home page. Will default to the github url if a github repository.
If a jQuery project, the version of jQuery the project requires. Must be a valid semantic version range descriptor.
The license(s) for the project. Multiple licenses are separated by spaces. The licenses built-in are: MIT, MPL-2.0, GPL-2.0, and Apache-2.0. Defaults to MIT. Add custom licenses with init.addLicenseFiles.
The primary entry point of the project. Defaults to the project name within the lib folder.
The name of the project. Will be used heavily throughout the project template. Defaults to the current working directory.
The version of Node.js the project requires. Must be a valid semantic version range descriptor.
The command to run tests on your project. Defaults to grunt.
Project's git repository. Defaults to a guess of a github url.
A human readable project name. Defaults to the actual project name altered to be more human readable.
The version of the project. Defaults to the first valid semantic version, 0.1.0.