paazmaya.fi

The Website of Juga Paazmaya | Stories about Web Development, Japanese Martial Arts, Hardware prototyping and travelling

Creating a Grunt plugin for running common tasks

During development same tasks are repeated over and over again, thus Grunt task runner came to existence.

It is living with a rule of one tool for one task, which is why there are already so many Grunt plugins.

This tutorial goes through the steps for creating such a plugin.

The versions used in the examples are the latest releases at the time of writing, such as Node.js v0.10.19 (inluding npm v1.3.11) and Grunt v0.4.1.

First decide an unique name, by looking at possible conflicting candidates at nmpjs.org.

In this example, I have decided to go with the name grunt-togeojson since it is a Grunt plugin, thus prefixed with grunt, and since it is using another tool, called togeojson, it is appended to the name.

As for my own contribution, it is only to combine those two by providing a list of files via Grunt, that are used by the toGeoJSON.

Initialisation

First start by creating a Git repository and link it to the GitHub repository which should be created as well. Below is an example of the commands used for creating local repository in the current folder, which is then linked to the GitHub repository URL.

On the GitHub side, just create empty repository without any predefined .gitignore nor README files.

git init
git remote add origin https://github.com/paazmaya/grunt-togeojson.git

Second step is to initialise the Grunt plugin project in the repository folder. This is done with the grunt-init tool, which can be installed with the following command:

npm install -g grunt-init

The grunt-init tool itself will not know how the Grunt plugin should be structured, but this can be done with a template. In order to get the template, run the following command:

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

Now the template should be available and it can be used as the following command shows:

grunt-init gruntplugin

After answering the questions which the grunt-init asks and based on the answers and the rules in the template, the basic structure for the Grunt plugin project has been created. You can now add those files to the repository and make the first push to GitHub:

git add -A
git commit -m "Initialisation of Grunt plugin"
git push -u origin master

Of course it is a good idea to check the contents of those files first, but there should not be anything alarming…

Adding dependencies

Next thing that might be needed, depending on the goal of the project, is to add dependencies on the tools which are used with the plugin.

For example, below is how in the case of toGeoJSON it is added to the dependencies with the command:

npm install togeojson --save

More information about the npm install specific command line arguments and options are available in the related documentation.

Automatic testing with Travis CI

The template used for creating the project also included Nodeunit based unit tests, which are available in the test folder.

Those tests are usually run manually with the command grunt test. They can also be triggered every time a commit in the GitHub repository occurs, with Travis CI].

Enable automated testing at the Travis CI profile page, by enabling the given repository that is currently being constructed.

Now a configuration file, called .travis.yml, needs to be added in the repository and it should have the following contents (in YAML format):

language: node_js
node_js:
  - "0.10"
before_script:
  - npm install -g grunt-cli

The file can be pushed to the repository with the commands:

git add travis.yml
git commit -m "Travis CI enabled"
git push

Once Travis CI has been testing the given GitHub repository, an image containing the current state of the tests can be added in the README.md. For example like this:

[![Build Status](https://travis-ci.org/paazmaya/grunt-togeojson.png?branch=master)](https://travis-ci.org/paazmaya/grunt-togeojson)

Which results in an image like this: Build Status

Publish to NPM

Once the plugin s doing what it is expected to do, it can be published to the NPM repository, so that others can enjoy the work of this plugin.

Make sure that the README.md and package.json are with up to date documentation and valid examples of how to use the plugin.

By adding the keyword gruntplugin to the package.json, the plugin will also be listed in the Grunt plugins page. Since the grunt-init was used with the gruntplugin template, the keyword should have been already added.

The set of commands below are for creating a Git tag, pushing it to GitHub repository, and finally publishing the plugin to NPM repository.

By default the first version is 0.1.0 but anything else is fine too, as long as it is reflecting the level of the readiness of the plugin for its goal.

git commit -am "Releasing v0.1.0"
git tag v0.1.0
git push
git push --tags
npm publish

The last command of making a release, npm publish, has further documentation at npmjs.org.

After a moment, the plugin should be available at the address:

https://npmjs.org/package/grunt-togeojson

Also there should be a release marked at GitHub repository.

Keep the project alive

Once the plugin has been published, tweet about it, make it visible.

After some time others will start using it and might file bugs, feature requests and other issues. Responding to those, fixing bugs, adding new features and accepting pull requests is what social coding is about.