Writing a donejs plugin

DoneJS generators run when the user types donejs add foo. These are special generators used to add functionality to an application. One example of a generator is donejs-cordova. This guide will walk you through writing an example generator, donejs-foo. We'll walk through an example where the user types:

donejs add foo bar

Create donejs-foo project

When the user types donejs add foo DoneJS will npm install the donejs-foo package. Any time you want to create a donejs generator simply give it a package name of donejs-NAME and publish it to NPM.

Create a new project folder and run npm init and answer the questions; the name of the project will be donejs-foo, the rest is up to you.

Write generator

There are 2 ways to structure donejs-foo; with a single generator or with multiple generators.

Multiple Generators

A plugin can have multiple generators associated with it. Open up the file you specified as the main in your package.json and write this:

exports.default = require("../default/index");
exports.bar = require("../bar/index");

Let me explain what this says. This tells DoneJS that there are 2 generators for this plugin; the default and bar generators. In the case of our example when the user types donejs add foo bar the bar generator is the one that will be run. If the user hadn't specified an argument then the default generator would be the one that is ran.

Single Generator

The other option is to specify a single export for your module which will act as the plugin's only generator. Reopen your main and write this:

module.exports = require("../default/index");

This says that the module default is the single generator for donejs-foo.

Now that we understand the two types of generators let's make this one actually do something. Create the folder in the root of your project called default and open a file index.js and write this:

var generator = require("yeoman-generator");
var fs = require("fs");

module.exports = generator.Base.extend({
  constructor: function(){
    generators.Base.apply(this, arguments);

    this.argument("name", {
      type: String,
      required: true
    });
  },

  writing: function() {
    var done = this.async();
    var outputPath = this.destinationPath("foo");

    // This should be "foo"
    var name = this.name;

    fs.writeFile(outputPath, "bar", function(err){
      done();
    });
  }
});

Generators can do many things such as prompt users for questions that help with configuring the generator; in our example we are simply writing out to a file foo in the user's project folder.

Registering

The next step would be to publish to NPM, but since this is just a test project there's no need to publish it. Instead you can test your plugin by typing:

npm link

This will make it available on your computer for testing. Create a new DoneJS project (or use an existing project you have) and run:

donejs add foo bar

The generator should be installed and ran and the result should be a foo file in your project's folder.

That's it! If this were a real plugin you'd next run npm publish to publish the project to NPM for others to use. For a more complete example check out donejs-cordova.