Yeoman logo

An Introduction to Yeoman

By Tyler Crammond, published Friday, January 30th, 2015


Yeoman is a command-line tool for setting up new projects and speeding up your development workflow. We’ve been using it for a few months now at PodPea and it’s proved invaluable.

If you’ve never heard of or at least not used Yeoman before, I hope this very basic example will help demonstrate the kind of thing it can do for you. So let’s get started:

Yeoman is based around ‘generators’ that are usually created by the community. A generator first sets up your project (this could be a very advanced and customized process) and from then on you can ask it to generate additional components. For example, an API generator of your favourite flavour could provide the ability to generate new routes with a single command. Pretty awesome!

For this example we’re going to use a generator I wrote for demonstration purposes, called generator-simple-html, to create a simple HTML website powered by LESS, with Grunt tasks included to boot.

Requirements

Before continuing you’ll need nodejs and npm installed.

Installation

We first need to install Yeoman and then the generator we want to use.

npm install -g yo && npm install -g generator-simple-html

 

The -g tag will install these modules globally so they’re always available and don’t have to sit around inside your project.

Scaffolding the project

Now we can start creating our project. Create a new folder for the project and move into the folder.

mkdir myProject
cd myProject

Only one command is needed to start generating the project. It’s important that you don’t run the generator in the wrong directory.

yo simple-html
  • yo is the command for Yeoman. Yo!
  • simple-html is the name of the generator we want to use. Running `yo` with only the name of the generator as a parameter, as we’ve done, will scaffold a new project.

You should now see a greeting from Yeoman and a prompt to enter a name for your website:

[?] What is your site’s name? (My Simple Website): 

Hit enter to use the default name or roll with one of your choosing. npm install and bower install will then be run automatically to install dependencies.

The most sophisticated generators give many choices when setting up a project. In the case of web technologies they would typically ask if you want to use X or Y CSS framework with I or J scripting language.

The result

So what has actually happened? This is what Yeoman should have generated for us:

Project structure

.
├── bower_components/
├── node_modules/  
├── less/
|   ├─ main.less
|   └─ variables.les
├── www/
|   ├─ css/
|   |  └─ main.css
|   ├─ img/
|   ├─ js/
|   └─ index.html
├─ bower.json
├─ Gruntfile.js
└─ package.json
  • bower.json – contains our project’s front-end dependencies.
  • package.json – contains our project’s node dependencies.
  • Gruntfile.js – Grunt tasks for our project. More on this shortly.
  • less/ – contains our project’s LESS files.
  • www/ – contains our website.

Diving into the www/ directory, we can see that the generator has scaffolded a basic folder structure for us and created an index file.

Grunt tasks

One of the immediate benefits of using a generator is that a wide selection of Grunt tasks will (usually) be included.

The simple-html generator includes a couple of Grunt tasks:

  • grunt less – compiles our LESS from less/main.less into CSS in www/css/main.css.
  • grunt serve – runs a server on http://localhost:9000.

This is one of my favourite features. Whenever you make a change to any LESS or HTML file while the server is running, the CSS will automatically be recompiled and any pages you have open will automatically refresh. If you’ve never experienced live-reloading like this before, this might be a moment of magic for you!

Let’s run grunt serve to start up a web server and check it out at http://localhost:9000. You should see the test page.

Time to try out the live-reloading jazz I mentioned above if you haven’t already. Open up less/main.less and save a change. Your browser should automatically refresh and reflect the changes to the CSS. Lovely!

Adding additional components

Most generators include “sub-generators” that allow you to add additional components to your project. This is so awesome – it can save a huge amount of time and tedious repetition across the lifetime of your project.

The simple-html generator has a sub-generator to create a new page. Go ahead and try it out:

yo simple-html:page my-page

You’ll see that a new page has been added to your project, my-page.html. It already includes the essentials of our project and some demo content, saving us a little bit of effort. In a real project / generator this would of course be used for greater purposes!

Let’s break down the command:

  • yo simple-html – as before, this is telling Yeoman that we want to use the simple-html generator.
  • :page – note the colon. This tells Yeoman that we want to use the sub-generator called page.
  • my-page this is the name to be given to the page. There are no other parameters for this sub-generator.

Most generators follow the above pattern, but you’d need to refer to their own documentation.

Next steps

There’s almost no limit to what can be achieved with generators. Have a browse through the Yeoman generator directory, find one for your technology stack and play about with it. You’ll be amazed.

Notable generators:


This post was originally featured on the author’s personal blog at tylercrammond.com.