Quickstart your webapp

Photo Credit: http://addyosmani.com

Quickstart your webapp

There are myriads of JavaScript frameworks and libraries out there, and as every ambitious web developer eager for knowledge to soak up, you want to test them all.

Maybe the new shiny one just mentioned on Hacker News is exactly what the doctor ordered for your next project? Yeah, that's you.

What we need is a fast and convenient way to get started. We want a basic website structure which doesn't hurt our eyes. Coffeescript and Sass should be wired up, and changes should be visible immediately. Enter the Yeoman workflow.

The Yeoman workflow

Yeoman helps you kickstart new projects, prescribing best practices and tools to help you stay productive.

To do so, we provide a generator ecosystem. A generator is basically a plugin that can be run with the yo command to scaffold complete projects or useful parts.

So basically we'll use Yeoman to bootstrap our environment with the features implemented by one of its generators. The rest (e.g. third-party dependencies) is the domain of Bower and Grunt.

Each of these projects are independently maintained by their respective communities, but work well together as a part of a prescriptive workflow for keeping you effective -- yeoman.io.

Yeoman is distributed via the Node.js package manager npm, so step 0 is to set up npm first. Then, the Yeoman setup is simply:

# The  --global argument will cause npm to install the package globally
# rather than locally. This means 'yo' is available in every directory.
% npm install -g yo
% yo -v
1.3.3

If we run yo without arguments, a nice interface presents us options to run a generator shipped with Yeoman or install new ones. Now, we focus on the most famous Yeoman generator for web apps.

generator-webapp

Yeoman's generator-webapp scaffolds out a front-end web app, with all the features we want (and more). The Github page lists:

  • CSS Autoprefixing
  • Built-in preview server with LiveReload
  • Automagically compile CoffeeScript & Sass
  • Automagically lint your scripts
  • Automagically wire up your Bower components with grunt-wiredep.
  • Awesome Image Optimization (via OptiPNG, pngquant, jpegtran and gifsicle)
  • Mocha Unit Testing with PhantomJS
  • Bootstrap for Sass (Optional)
  • Leaner Modernizr builds (Optional)

Setup

To get started, we install the generator and invoke it with yo:

# install the generator
% npm install -g generator-webapp

# a place for our webapp project
% mkdir webapp && cd $_

# generate structure, with Coffeescript support
yo webapp --coffee

The friendly generator includes HTML5 Boilerplate, jQuery and a Gruntfile. Additionally, we opt to include Sass in the menu. After the intimidatingly long list of components has been installed, we can look at the result.

Fire up the webapp with:

grunt serve

Your default browser should open Yeoman's welcome page ('Allo, 'Allo!), always up to date thanks to LiveReload. The browser console should show 'Allo from CoffeeScript!. If you get a Ruby Sass error, install the missing gem with gem install sass.

Webapp structure

The files of our webapp are neatly structured in the app/ directory.

▾ app/
  ▾ images/
  ▾ scripts/
      main.js
  ▾ styles/
      main.scss
    favicon.ico
    index.html
    robots.txt

Go ahead, open app/index.hml and change the <h1> gretting. Saving the file should result in an immediate update in the browser.

Third-Party Dependencies

Third-party dependencies are managed with grunt-wiredep. The bower-grunt duo removes the chore to manually download, say, jQuery, place it in the correct directory and link it in index.html. The same with updates.

How about this:

bower install --save jquery
grunt wiredep

Because jQuery--together with a lot of other projects--follows the Bower spec, the library is wired up in index.html like this:

<!-- bower:js -->
<script src="bower_components/jquery/jquery.js"></script>
<!-- endbower -->

If this doesn't work with the bower project you want to try, you can always manually add the dependency (the <script> or <style tag) by yourself.

An example workflow

Let's try the Yeoman workflow to check out marka:

Beautiful transformable icons built for the web.

# our project dir
% mkdir marka && cd $_

# scaffold the webapp, without coffeescript this time
yo webapp

# let's see if we can find a bower package for 'marka'
bower search marka

# yup, install it! Don't forget '--save'
bower install --save marka
grunt wiredep

bower list shows the dependencies it currently knows of:

marka /Users/sven/Code/marka
├─┬ bootstrap#3.2.0 (latest is 3.3.1)
│ └── jquery#2.1.1
└── marka#0.3.1

Changes

Everything should be ready now to start playing around with Marka. I changed these files:

  • index.html to include test icon
  • app/scripts/main.js to initialize icon and change on click
  • .jshintrc to suppress linting warnings
<!-- index.html -->
<i id="icon"></i>
// app/scripts/main.js
$(document).ready(function() {
  'use strict';

  var m = new Marka('#icon');
  m.set('circle')
    .color('#00B4FF')
    .size('100');

  $('#icon').click(function(){
    m.set('plus');
  });

});

To make the jshint task happy, I included the following in .jshintrc:

  ...
  "globals" : {
    "Marka": false
  }
The Marka icon inserted into the bootstrapped site, ready for more awesome stuff.

Conclusion

This article showed a quick way how to bootstrap a modern web app. Some highlights:

  • one-command bootstrap of webapp (generator-webapp)
  • LiveReload functionality to watch what we're doing
  • dependency management with bower and grunt-wiredep

And this is far from all. Lot's of grunt tasks we didn't even talk about (image optimization, file compression, ...) and other goodies however deserve another article.

Happy bootstrapping!

Further resources