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:
[](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:
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.