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.
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
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
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:
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...
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:
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
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.