You are currently offline, so some features of this site may not work fully.

Your browser doesn’t support some of the latest CSS features used to build this site.

Read more about my usage of new CSS features.

Another post in the “Ain’t Scary” series, this post introduces Yeoman, the “Web’s Scaffolding Tool for Modern Webapps” and gives an example of a basic generator setup.

Yo man!

I was first introduced to Yeoman by Mr. Addy Osmani at London JS Conf last year in his Web Components Can Do That?! talk.

As I looked further into Yeoman, I could see the use cases and trying it out with generators for HTML5 Boilerplate and Angular were pretty cool.

Yeoman logo
Yeoman’s a friendly guy.

It seemed quite daunting - scary, if you will, to write my own generator to scaffold a basic project but I gave it a good go again recently and picked up some tips along the way to share.

Prerequisites

Generating all of the things

First off, run the generator generator to generate all of the things:

$ yo generator
Yo Dawg, I heard you like generators meme
Yo Dawg, I heard you like generators

You’ll then be asked a series of questions to kick off your generator setup and will end up with a basic directory structure and a few files - something like this:

  
    - app
    - index.js
    - templates
    - _package.json
    - test
    - test-app.js
    - package.json
    - README.md
  

Setting up your templates

Next what I do is set up additional project meta files to be copied over when you use the generator - these have to reside in the /app directory.

I’ll start with a .gitignore, .editorconfig, yourProject.sublime-project file along with a README.md for the project and optionally (more on optionally later) a .travis.yml config for the CI build process.

Next up I’ll give my generator some buddys - Grunt and Bower play pretty nicely with Yeoman!

A sample bower.json

Furthermore I’ll create a base set of dependencies with a bower.json file.

A sample Gruntfile.js

Lastly in the setup stage I’ll add in a sample Gruntfile.js from one of my other projects, stripped back to a more generic reusable implementation.

Copying your templates

The first bit of real Yeoman magic is to copy over your template files.

If you’ve used the generator-generator you’ll have an index.js in which you’ll find two functions named writing.app() or writing.projectfiles() where you can use this.src.copy() to copy over the files you added to templates and this.dest.mkdir() to create directories for them to reside in.

  
    writing: {
      app: function () {
        this.dest.mkdir('app');
        this.dest.mkdir('app/templates');

        this.src.copy('_package.json', 'package.json');
        this.src.copy('_bower.json', 'bower.json');
      },

      projectfiles: function () {
        this.src.copy('editorconfig', '.editorconfig');
        this.src.copy('jshintrc', '.jshintrc');
      }
    }

Scaffolding

Now the real fun begins!

You’ll notice Lo-Dash style delimiters in the templates <%= %>. These are to be used when running the generator to allow a user to pass options via the command line and scaffold the files with the input. This is where the true power of the Yeoman generator happens!

Still in your index.js you’ll see a function called prompting().

In here you write command line prompts for someone using your generator (probably you) to respond to, dictating the scaffolding and setup of the project.

When these questions are asked the responses are passed through to your generator and are accessible in the templates, for use with those Lo-Dash delimeters we saw before.

Here’s a couple of examples of what I use these prompts for:

  • What’s your project name? → scaffold README.md with project name
  • Do you need jQuery? → scaffold bower.json with jQuery
  • Where would you like Bower components installed to? → scaffold .bowerrc with destination
  • Will you have a Travis CI build? → add .travis.yml copy to your index.js

Voila

And there you have your first basic Yeoman generator!

To test it out:

  1. Link your generator locally: $ npm link
  2. Create and enter a new directory: $ cd ~/Desktop/ && mkdir yourProject && cd yourProject
  3. Fire away! $ yo generatorName

Publishing your generator

The last step is to publish your generator when you’ve scaffolded a few more files and directories.

Prerequisites

All you need, if you’ve not set up an NPM user on your machine is to do so by entering the following command and following the instructions:

$ npm adduser

When done, publish it:

$ npm publish

Simple as that! And it wasn’t that scary, right?

A screenshot of my Yeoman generator in action

TL;DR

Follow these simple instructions to create your first Yeoman generator and scaffold a simple project.

See an example of one of my generators, generator-furzeface on GitHub.

For more short introductions to the latest front end technologies, follow the “Ain’t Scary” series on my blog.