Learning Yeoman

The Yeoman toolset runs in the Node.js environment and is invoked from the command line. Each tool is installed using Node's package manager (npm) and uses the npm repository to manage all plugins.

Before we dig deep into using each tool of the workflow, let's take a look at some of the Yeoman tooling features that will help you in your next project:

The preceding features are dependent on what the individual generators provide via Grunt tasks. By default, the Angular, Backbone, Ember, and other webapp generators provide tasks to perform all the features listed.

Modern tools usually mean more tools to learn, but learning the tools of the Yeoman workflow is easier than you think. To demonstrate by example, here is how easy it is to get a modern web application up and running, all from the command line.

$ npm install -g yo

$ npm install -g envcheck

$ npm install -g generator-webapp

Yeoman includes a powerful command-line utility that can scaffold files based on individual generator templates, allowing you to save time creating files from scratch. There are over 700 community generators on npm.

Invoking the generator

Yo, the scaffold tool, will easily create and set up project configuration, files, and folders needed for a modern web application. Execute the following command:

$ yo webapp

Generators can be invoked with different options; in the preceding command, we use the generators' default options that include Mocha as the test framework and JavaScript as the scripting language. You will get an output similar to the following screenshot:

The preceding command does many things. First off, it's going to ask you a few questions about your new project, such as whether to include Twitter Bootstrap with or without Compass SASS and whether to include Modernizr.

Select the first option (Bootstrap), and press Enter; you will see the output to the terminal, and Yeoman is performing all the magic right before your eyes.

├── Gruntfile.js
├── app
│   ├── 404.html
│   ├── bower_components
│   │   ├── bootstrap
│   │   └── jquery
│   ├── favicon.ico
│   ├── images
│   ├── index.html
│   ├── robots.txt
│   ├── scripts
│   │   └── main.js
│   └── styles
│       └── main.css
├── bower.json
├── node_modules
├── package.json
└── test
    ├── bower.json
    ├── bower_components
    ├── index.html
    └── spec

Yeoman includes Grunt, a task-based command-line tool for JavaScript projects. It is used to perform various build tasks on projects and exposes several useful tasks that you will want to use in your workflow. Yeoman automatically creates and configures Gruntfile.js, which specifies the configuration of the tasks and targets.

The following order of commands is used for a seamless development workflow:

$ yo webapp                   #scaffold application
$ bower install jquery        #install dependency
$ grunt serve                 #start preview server
$ grunt test                  #run unit tests
$ grunt                       #create optimized build

Generally, a modern web developer's workflow consists of the following steps:

To view all the installed grunt tasks associated with the project, you can use the grunt –h command, which will output a list of all tasks and their descriptions.

Now that you have all the initial files and folders for the project, you can really start to see the power of Yeoman.

Previewing the server

Connect LiveReload is the module that is a server that will auto reload when files are changed by the watch process.

To preview the application, execute the following command:

$ grunt serve

The serve task does a few things, which are as follows:

1. First, it removes all the files in the .tmp directory via the clean task.

2. It starts the Connect LiveReload server located at 127.0.0.1:9000, and opens the default web browser via the connect task.

3. Then, finally, it runs the watch task that monitors the project's source (app/*) files, thus executing subtasks on changes.

Your default browser should have opened up, displaying the following page:

Yeoman includes an excellent tool called Bower, which is a package manager for the Web and allows you to easily manage dependencies for your projects. Packages can include any type of assets such as JavaScript, images, and CSS. Twitter and the open source community actively maintain it.

Here are some of the available Bower commands:

Let's go ahead and add a templating library to our webapp to handle the compilation of model data with HTML for the view. Open the terminal and execute the following command:

$ bower install handlebars --save

This command will download the Handlebars templating library and place the package in the app/bower_components directory.

To view all client-side dependencies associated with the project, just use the bower list command that will output a tree of all the installed components and their versions, and also inform us if updates are available, as shown in the following screenshot:

The preceding screenshot is the result of running the bower list command from within the project's root directory or the directory containing the bower.json file, which stores all the installed libraries.

The --save flag tells Bower to write the library name and version to the bower.json file located in the project's root directory. The bower.json file is how Bower manages the project's dependencies.

To wire up the newly downloaded package to the application's index.html page, execute the following grunt task:

$ grunt bowerInstall

This command will read the contents of the index.html file in the app folder. Then, look for the <!-- bower:js --> block and inject a script tag with the location of the component's main file for each package in the bower_components directory.

Yeoman includes JSHint, which is a linting tool that helps developers detect errors and potential problems in their JavaScript code; it is a great way to force best practices and improve the code quality. This is very useful when working with a large code base or in a team environment.

The jshint task is responsible for linting all code before it gets executed. The following screenshot shows an example of using the jshint task. It displays the errors that output when code fails the linking process:

Let's begin to add some logic to the applications' main script file that was created during the initial scaffold. Open app/scripts/main.js and add the following:

/* global Handlebars */
(function () {
  'use strict';
  window.App = {
    init: function (config) {
      console.log( '1 - initialize' );
      this.config = config;
      if (this.config.feature && this.config.feature.endpoint) {
        this.fetch();
      }
      return this;
    },
    render: function () {
      console.log( '4 - render' );
      var template = Handlebars.compile( $( this.config.el ).find( 'script[type="text/x-handlebars-template"]' ).html() );
      var html = template( this.config );
      $( this.config.el ).html( html );
      return this;
    },
    onSuccess: function (response) {
      console.log( '3 - onSuccess' );
      this.config.features = response;
      this.render();
    },
    onError: function (error) {
      return this.log( error );
    },
    fetch: function () {
      console.log( '2 - fetch' );
      var self = this;
      $.ajax( {
        url: self.config.feature.endpoint,
        dataType: 'jsonp',
        success: function (results) {
          return self.onSuccess( results );
        },
        error: function (error) {
          return self.onError( error );
        }
      } );
    }
  };
})();

console.log( 'Allo, Allo!' );

Here is the breakdown of the preceding code:

Save the file, and the lint task will then compile into JavaScript and reload the browser; nothing will look different because we haven't added the application's template.

Yeoman comes with a watch task that is responsible for the automation of different tasks when developing web applications, such as compiling CoffeeScript to JavaScript when source files change or concatenating and parsing SASS files and then reloading the web browser to see changes.

The automation tasks are limited to the Grunt tasks that are defined by the generator; any changes to the .js or .html file in the app directory will automatically get parsed, and the browser will get refreshed. If the watch task detects changes to files in the test directory, then the unit tests are run via the test task.

Let's create the application's template; we will use the {{ }} double mustache syntax to render the dynamic content. Open the app/index.html file, and add the following contents inside the body element right below the browsehappy code line:

...  
<![endif]-->
  <div class="container">
    <script type="text/x-handlebars-template">
      <div class="header">
        <ul class="nav nav-pills pull-right">
          <li class="active"> 
             <a href="/">Home</a>
          </li>  
          {{#each menu}}
          <li>  
            <a href="#{{route}}">{{name}}</a>
          </li>
          {{/each}}
        </ul>
        <h3 class="text-muted">{{sitetitle}}</h3>
      </div>
      <div class="jumbotron">
        <h1>{{feature.title}}</h1>
        <img src="{{feature.image}}"/>   
        <p class="lead">{{feature.body}}</p>
      </div>
      <div class="marketing">  
        {{#each features}}
        <div class="media">
          <a class="pull-left"> 
            <img src="{{ image }}" class="img-thumbnail"/> 
          </a>
          <div class="media-body">
            <h4 class="media-heading">{{ title }}</h4>
            <p>{{ body }}</p>
          </div>
        </div>
        {{/ each }}
      </div>
      <div class="footer">
        <p>{{sitecopy}}</p>
      </div>  
    </script>
  </div>
  <!-- build:js scripts/vendor.js -->

The preceding code is very similar to the HTML that was created by Yeoman, except we are replacing the static content with data for Handlebars to compile the template with dynamic configuration data. Now, let's initialize the application by adding the following script block at the bottom of the app/index.html file in the app folder that was created during the initial scaffold:

  <!-- build:js({app,.tmp}) scripts/main.js -->
  <script src="scripts/main.js"></script>
  <!-- endbuild -->
  <script>
    $(document).ready(function() {
      App.init({
        el: '.container',
        sitetitle : 'Learning Yeoman',
        sitecopy : '2014 Copyright',
        version: '0.0.1',
        feature : {
          title : 'Chapter 1',
          body : 'a starting point for a modern web app.',
          image : 'http://goo.gl/kZZ6dX',
          endpoint : 'http://jonniespratley.me:8181/api/v2/learning-yeoman-ch1/posts'
        },
        features : null,
        menu: [
          {name: 'About', route: '/about'},
          {name: 'Contact', route: '/contact'}
        ]
      });
    });
  </script>

In the preceding code, we perform the following steps:

If testing is not a part of your workflow, it should be! Yeoman makes it incredibly easy to test your application by setting up a testing environment with the Mocha framework. Other options include Jasmine, QUnit, and just about any other framework. That helpful robot (Yeoman) just saved hours of development time by creating all the necessary configuration files during the initial project scaffold.

Several testing tasks can be customized to do many useful things like showing test results in JUnit for use in many continuous integration systems such as Jenkins and Bamboo. Perform the following steps:

Running tests

To run the tests, use the following command:

$ grunt test

The output in the console should look similar to the following screenshot:

As we can see from the output, the configuration of PhantomJS is already taken care of. It nicely starts the PhantomJS browser; after connecting to the browser, it logs the output to the console as the tests run.

The default Grunt task ($ grunt) takes care of optimizing your entire project by doing the following:

See for yourself; open Chrome Developer Tools and click on the Network tab.