Grunt - Create your custom local Grunt plugin

This post describes how you can write your own Grunt Plugin in Javascript and install it locally,
in order to use it on your own (Grunt) project build file.

If you don't know what Grunt is then to explain it on one leg -
"Grunt is a pluggable (JavaScript) task runner", which can be used to build JavaScript projects.

Such typical build of a Javascript project may contain a Linting task, minification task, and so on...

So, you can read more about Grunt if you want to get a better understanding.

And now, to the recipe!
Ingredients:
1 NPM installed on your machine
1 GIT installed on your machine
1 Skill writing a tiny bit of Javascript
A zest of patience

Instructions:
1. First thing would be to install a Grunt plugin that is used for templates scaffolding.
In order to do that, you need to run the following in your shell:

$ npm install -g grunt-init

2. Clone a GIT repository which is going to be used as your template for creating your glorious
Grunt Plugin. (https://github.com/gruntjs/grunt-init-gruntplugin)
So, run the following in your shell:

$ git clone https://github.com/gruntjs/grunt-init-gruntplugin.git ~/.grunt-init/gruntplugin

3. Create an empty directory where you want to place your Plugin like "my-custom-plugin", and cd into it.

$ mkdir my-custom-plugin
$ cd my-custom-plugin

Then run the following in your shell:

$ grunt-init gruntplugin

4. You should now be prompted with a serie of questions in the shell, in order to create your plugin.
You should be seeing something like this:

Please answer the following:

[?] Project name (grunt-my-custom-plugin)

[?] Description (The best Grunt plugin ever.) the best custom plugin ever!

[?] Version (0.1.0)

[?] Project git repository (ssh://<Your GIT remote Repository URL>)

[?] Project homepage (none)

[?] Project issues tracker (none)

[?] Licenses (MIT)

[?] Author name (nirgit) Nir M

[?] Author email (getnirm@gmail.com)

[?] Author url (none) tech-drum.blogspot.com

[?] What versions of grunt does it require? (~0.4.2)

[?] What versions of node does it run on? (>= 0.8.0)

[?] Do you need to make any changes to the above before continuing? (y/N) N



Writing .gitignore...OK

Writing .jshintrc...OK

Writing Gruntfile.js...OK

Writing README.md...OK

Writing tasks/my_custom_plugin.js...OK

Writing test/expected/custom_options...OK

Writing test/expected/default_options...OK

Writing test/fixtures/123...OK

Writing test/fixtures/testing...OK

Writing test/my_custom_plugin_test.js...OK

Writing LICENSE-MIT...OK

Writing package.json...OK



Initialized from template "gruntplugin".

You should now install project dependencies with npm install. After that, you

may execute project tasks with grunt. For more information about installing

and configuring Grunt, please see the Getting Started guide:



http://gruntjs.com/getting-started



Done, without errors.

5. Now you should have your directory containing a Grunt Plugin template.
Open the file you have inside the "tasks" directory in order to edit it.

6. The file should look as follows:

7. Just in order to get started, lets strip the file and change it to contain the following:

/*
 * grunt-my-custom-plugin
 * 
 *
 * Copyright (c) 2014 Nir M
 * Licensed under the MIT license.
 */

'use strict';

module.exports = function(grunt) {

 grunt.file.defaultEncoding = 'utf8';

 // Please see the Grunt documentation for more information regarding task
 // creation: http://gruntjs.com/creating-tasks

 grunt.registerTask('my_custom_plugin', function() {
  grunt.log.writeln('Hello my great Grunt Plugin!') ;
 });
};

The my_custom_plugin shown in bold above, is the name of your task in the Grunt build, that
you'll execute at the end.

Lets change the Gruntfile.js in the root directory of the Plugin so tests won't execute when
we will run "grunt" on the plugin's source. Otherwise the build would fail.
So now the Gruntfile.js last line should look like:

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

8. Go back to the root directory of your Grunt Plugin and run the following:

$ npm install

$ grunt


Running "jshint:all" (jshint) task

>> 3 files lint free.



Done, without errors.

9. Almost done.
Now go to your own project where you want to use your plugin and add the following line to the
Gruntfile.js of your project:

grunt.loadNpmTasks('grunt-my-custom-plugin');

This will load your Grunt plugin task to your Grunt's project.

10. Next step would be to install the plugin locally in the node modules of your Proect.
You should now run in the root directory of your Project (where you want to use your plugin) the following:

$ npm install /<PATH_TO_YOUR_PLUGIN>/my-custom-plugin

11. You should now be able to execute:

$ grunt my_custom_plugin

And see:

Running "my_custom_plugin" task

Hello my great Grunt Plugin!



Done, without errors.

That's all folks.
Hope this was helpful to get you started with Grunt Plugins.
Don't forget to publish it (npm publish) afterwards to the rest of the Node community if you think it may be helpful to others as well.

Check out the official guide for creating Grunt plugins at:
http://gruntjs.com/creating-plugins

Good luck!