Yeoman is basically a tool for generating scaffolding, i.e. predefined projects (see generators for a list of some existing generators).

You could generate things other than code/projects equally well using yeoman.

There’s a fair few existing generators but you can also define your own generators and hence… Say for example you have a standard set of tools used to create your Node based servers, i.e. you want Typescript, express, eslint, jest etc. we could use yeoman to set everything up.

Ofcourse you could create a shell script for this or a custom CLI, but yeoman gives you the ability to do all this in Javascipt with the power that comes from that language and it’s eco-system.

Within a yeoman script, we can also interact with the user via the console, i.e. ask for input. Create templates for building code, configuration etc.

Installing the tooling

Before we start using yeoman we need to install it, so run either npm or yarn as shown below

npm install -g yo 

To check everything worked simply run

yo --version

At the time of writing, mine version is 3.1.1.

Before we get onto the real topic of this post, lets just check out some yeoman commands

• Listing installed generators

  yo --generators
  

• Diagnose yeoman issues

  yo doctor
  

Creating our own generators

Okay so this is what we’re really interested in. I have a bunch of technologies I often use (my usual stack of tech./packages). For example, if I’m creating a Node based server, I’ll tend to use Typescript, express, jest and so on. Whilst we can, ofcourse, create things like a git repos with everything set-up and just clone it or write shell scripts to run our commands. As mentioned, with yeoman we can also template our code as well as interact with the user via the CLI to conditionally generate parts of our application.

There appears to be a generator for producing generators, but this failed to work for me, but for completeness here it is

npm install -g yo generator-generator

Now, let’s write our first generator…

Run the following, to create our package.json file

yarn init -y

The first thing to note is, the generator name should be prefixed with generator-. Therefore we need to change our “name” within package.json, for example

"name": "generator-server"

The layout of our files is expected to be a either (off of our root)

packages.json
generators/app/index.js
generators/router/index.js

OR

packages.json
app/index.js
router/index.js

Whichever layout we choose should be reflected in package.json like this

"files": [
    "generators"
  ],

OR

"files": [
    "app",
    "router"
  ],

You might, at this point, wonder what the point of the router is, and whilst this is within the yeoman getting started guide, it appears ultimately any folder added alongside the app folder will appear as a “subcommand” (if you like) of your generator. In this example, assuming the app name is generator-server (see below) then will will also see that router can be run using yo server:router syntax. Hence you can create multiple commands under your main yeoman application.

We’ll also need to add the yeoman-generator package before we go too much further, so run

yarn add yeoman-generator

So here’s a minimal example of what your package.json might look like

{
  "name": "generator-server",
  "version": "0.1.0",
  "description": "",
  "files": [
    "generators"
  ],
  "keywords": ["yeoman-generator"],
  "dependencies": {
    "yeoman-generator": "^1.0.0"
  }
}

Writing our generator code

In the previous section we got everything in place to allow our generator to be recognised by yeoman, so let’s now write some code.

Here’s an example of a starting point from the yeoman website.

In generator/app/index.js we have a simple example

var Generator = require("yeoman-generator");
module.exports = class extends Generator {
   method1() {
      this.log('method 1 just ran');
   }
   method2() {
      this.log('method 2 just ran');
   }
};

Sadly this is not using ES6 syntax, maybe I’ll look into that in a future post, but for now it’s not too big of a deal. There is a @types/yeoman-generator package if you want to work with Typescript, but I’ll again leave that for another possible post.

When we get to run this generator, you’ll find that both methods are run hence we get the following output

method 1 just ran
method 2 just ran

All the methods we add to the Generator class are public as so are run by yeoman. We can make them private by prefixing with the method name with an underscore (fairly standard Javascript style to suggest a field or method to be private or ignored).

The order that the methods appear is the order they’re executed in, hence switching these two methods around will result in method2 running first, followed by method1.

We’re not going to write any further code at this point, I’ll leave coding the generator for another post.

Testing our generator

At this point we don’t want to deploy our generator remotely, but want to simply test it locally. To do this we run the following command from the root folder of our generator

yarn link

This will create a symbolic link for npm/yarn and now we can run

yo --generators

which should list our new generator, named server.

Now we have our generator available to yeoman, we simply type

yo server

Obviously server is replaced by the name of your generator.