MandalaTV
Personal and Professional Blog of Rich Hauck

Using Yeoman to Create a Website Workflow

by: Rich Hauck

Up until now, I’d always embarked on a new web project by either downloading all of the necessary components (HTML5 Boilerplate, JQuery, etc.) or keeping a local copy of such popular projects on my hard drive and copying them into to a new folder. I’d known about command line installers for quite awhile, but shied away from them as being too intimidating or complicated. I’d also worked in Sass, the CSS precompiler, but found debugging too frustrating, as (at the time) browser inspectors like Firebug didn’t provide support.

I’d say Yeoman has really changed all of this for me. It has generators to pull all of the necessary dependencies and publishes minified files that are optimal for performance. I always feel like I’m light years behind when I come across stuff like this, but seeing the source code of other sites helps let me know that I’m not that late to the ball.

Workflow

  1. First, ensure you have Sass installed.On Mac:
    Using a Mac? Congratulations, Macs ship with Ruby installed, so you’ll install Sass by opening up your Terminal (which you’ll find in Applications > Utilities) or iTerm and typing:

    gem install sass

    if you run into an error, it’s likely it’s a permission error, meaning you’ll need to install Sass using sudo (superuser do):

    sudo gem install sass

    Once installed, double check the installation by typing:

    sass -v

    This should return the version of Sass installed.

    On PC:
    you’ll want to run RubyInstaller.

    NOTE: In both cases, you may want to use Sass 3.3.0 alpha, as it supports CSS Source Maps.

    gem install sass -v '>=3.3.0alpha' --pre
  2. Next, you’ll need to download NodeJS. There is an installer that’s available for both PC and Mac (as well as a binary for Linux). This will also install Node Package Manager (NPM). NPM is Node’s collection of software libraries that automate installing, upgrading, configuring, and deleting scripts.
  3. With Node installed, you can proceed to install Yeoman. Yeoman is a scaffolding tool for automating the creation of Web applications. You can do this by opening up the Terminal (Mac) or Command Line (PC) and typing the following:
    npm install -g yo

    (Node is a global installation, meaning the above call should work regardless of which directory you are in in the command line). Yeoman automatically installs Grunt, a javascript task runner (which will build, watch, and publish files), as well as Bower, Twitter’s package manager.

    In order for Yeoman to generate a project, it needs to know what code generator to use. In this case, we’ll focus on webapp, which scaffolds out a front-end web application, or website template (and also happens to be the focus of the Yeoman website example).

    Yeoman’s website contains a list of official generators along with a list of community-contributed generators (I’ve found the Angular and WordPress ones to be particularly useful).

  4.  While in the command line, type:
    npm install -g generator-webapp

    and hit “Enter”. You should see a series of lines go be listing all of the dependencies being installed.

  5. Next, create a folder on your hard drive where you wish to install your website template (do this either in your operating system or by mkdir [foldername]). Then navigate to that folder in the Terminal. You can either do this by typing cd [path] or, if you’re lazy like me, typing “cd”+space and dragging the target folder right into the command line window.
  6. Once you’re in this folder, you can proceed to install the webapp by typing this in the command line:
    yo webapp

    yeoman

    Choose your options and it will install the following files and folder structure:

    • /app – This is where you will develop and modify your site template
    • bower.json – This is a file telling bower what library
    • /node_modules – This directory contains all of the dependencies required for the project and referred to in the Gruntfile.
    • Gruntfile.js – This file tells Grunt what to do with your app folder when you publish your app. It will include file minification and consolidation.
    • package.json – This file is used by Grunt to list all devDependencies. Leave devDependencies alone, however, you can modify your app’s name and version.
    • /test – This folder contains unit tests.
  7. Next, call the following in the command line:
    grunt serve

    This will create a static web server and open your default browser to point to your webapp’s app folder. You will want to use Firefox 29+ or the most recent version of Chrome, as these will support scss files in the web developer console.More importantly, calling grunt serve also does grunt watch, which means it will poll your /app folder for changes. As soon as you save any file, it will detect the change and reload the latest version in the browser.

    As this is happening, your command line window will show “Waiting…”. If at any point you wish to return to the prompt, you can type control+c to return to the prompt.

    In the past, I’d used the live view in Brackets (Adobe’s excellent open source text editor) or the Compass framework by itself. I’d still advocate Brackets, however, Grunt doesn’t break the connection between editor and browser when you open the developer console.

  8. Once you are satisfied with your app, you can return to the command prompt, type the following, and hit “Enter”:
    grunt build

    This will instruct Grunt to use the commands and preferences defined in Gruntfile.js and build out your app in a new folder: /dist (the location of this distribution folder can be changed in the Gruntfile.js under the yeoman project settings found in grunt.initConfig()).

By default, the webapp’s Gruntfile.js will include instructions to minify all files and images within the app folder. If you want to change any of the publish settings, you can simply change the Gruntfile. For example, if you want to prevent the HTML page from minifying (as I do, since I’m likely to inject server-side calls), you can either modify the preferences for htmlmin (L248) or comment out where Grunt registers the task (see grunt.registerTask() on L389).

I questioned this workflow every step of the way. I investigated ways to include CSS and Javascript source maps, then I tried revising the cachebusters to query strings instead of file name prefixes (until I discovered prefixes were more reliable). I also looked into using Koala as a watch tool instead of Grunt. In the end, I have no doubt this generator has gone under extensive scrutiny, and it’s something I’m currently building into my workflow.


Categories:HTML5 javascript webdesign
Comments: 0

Leave a Reply

Your email address will not be published. Required fields are marked *

About Rich Hauck

Rich Hauck

I'm a creative technologist at Hauck Interactive, Inc. and an adjunct instructor at HACC. I live in Harrisburg, Pa. with my wife and three boys. I enjoy good coffee, Trappist beers, Orioles baseball, and good design.


Archives