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 built-in templates with
grunt-init --help - Create a project based around a built-in template with
grunt-init templatename - Create a project based around a custom 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.
grunt-init currently includes these basic templates.
- commonjs - Create a commonjs module, including Nodeunit unit tests. (sample "generated" repo | creation transcript)
- gruntfile - Create a basic Gruntfile. (sample "generated" repo | creation transcript)
- gruntplugin - Create a grunt plugin, including Nodeunit unit tests. (sample "generated" repo | creation transcript)
- jquery - Create a jQuery plugin, including QUnit unit tests. (sample "generated" repo | creation transcript)
- node - Create a Node.js module, including Nodeunit unit tests. (sample "generated" repo | creation transcript)
If you're curious to see what these templates generate, cd into an empty directory, run grunt-init templatename, answer the questions, and inspect the result. Or check out the listed sample "generated" repos and creation transcripts.
You can create and use custom templates. Your template must follow the same structure as the built-in 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, just like the built-in templates.
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.
};Until these methods and properties are documented, see the grunt-init source for more information:
- https://github.com/gruntjs/grunt-init/blob/master/tasks/init.js
- https://github.com/gruntjs/grunt-init/blob/master/tasks/lib/helpers.js
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
Until these prompts are documented, see the grunt-init source for more information:
- https://github.com/gruntjs/grunt-init/blob/master/tasks/init.js
- https://github.com/gruntjs/grunt-init/blob/master/tasks/lib/prompt.js
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain
TODO: explain