Creating generators

Here is a quickstart guide to introduce the notion of generators, how they are defined, registered and used.

Packaging a generator

First, you need to decide whether you want a local-to-project generator (project specific) or a generator designed to be used across several projects / applications.

In the first case, all you need to do is to put your generators at the proper place within lib/generators directory.

Generators are registered per namespace, where most often is simply the relative path they were found minus the lookup paths (here $(pwd)/lib/generators). So if you create a generator at lib/generators/mygenerator/controller/index.js, then it should be registered as mygenerator:controller.

This works similarly for npm packages, with the additional requirement of naming it after the generator-* pattern. The package name must begin with this prefix for easier discovery (but you can still use the environment directly and register manually a non-conventional name, should you need it).

Simple format

This is the most basic way and have the benefit of not requiring you to depend on yeoman-generator.

// Example of a simple generator.
//
// A raw function that is executed when this generator is resolved.
module.exports = function() {
  console.log('Executing generator');
  console.log('Context is the Base object', this);
};

module.exports.name = 'You can name your generator';
module.exports.description = 'And add a custom description by adding a `description` property to your function.';
module.exports.usage = 'Usage can be used to customize the help output';

A simple function you expose through module.exports. You can optionaly attach name, description and usage properties on that function.

It takes a list of arguments (usually CLI args) and a Hash of options (CLI options), the context of the function is a new Generator.Base object, which means that you can use the API as if you were extending Base.

It works with simple generator, if you need to do a bit more complex stuff, extends from Generator.Base and defines your generator steps in several methods.

Please, bare in mind this way of doing so was added for conveniency, but generators works best in the scenario described above, which is the recommended way.

Extend format

wip

Meanwhile, you can check out yeoman's generator-* and the generated API documentation.