Creating a Grunt plugin for running common tasks

During development, the same tasks are repeated over and over again, leading to the creation of Grunt task runner. It adheres to a principle of one tool for one task, resulting in an extensive array of Grunt plugins. This tutorial outlines the steps for creating such a plugin. The versions referenced in this example are the latest releases at the time of writing: Node.js v0.10.19 (including npm v1.3.11) and Grunt v0.4.1.

First, choose a unique name for your plugin by checking for potential conflicts on [npmjs.org][] — in this instance, I’ve opted for grunt-togeojson as it is a Grunt plugin (prefixed with grunt) and integrates the togeojson tool (appended to the name). My contribution lies solely in merging these two by allowing Grunt to process a list of files used by toGeoJSON.

Initialisation

Start by creating a Git repository linked to a new GitHub repository (create it here). Use the following commands for setting up a local Git repository and linking it to your GitHub repository:

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

Next, initialize the Grunt plugin project within this repository using grunt-init:

npm install -g grunt-init

The grunt-init tool doesn’t know how to structure your Grunt plugin but uses a template for guidance. Retrieve the template with:

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

Now, utilize the template by running:

grunt-init gruntplugin

Answer grunt-init’s questions, and it will generate a basic Grunt plugin project structure. Add these files to your Git repository and make an initial commit:

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

Check the generated files before committing for any discrepancies.

Adding dependencies

Depending on your plugin’s requirements, you might need to include dependencies on tools utilized within it. For instance, adding togeojson as a dependency involves:

npm install togeojson --save

Refer to npm documentation for additional command line arguments and options.

Automatic testing with Travis CI

The template includes Nodeunit unit tests in the _test folder, usually executed manually via grunt test. For automated testing on every GitHub commit, use Travis CI.

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

Create a configuration file called .travis.yml in your repository with this content (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:

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.