03 March 2013

Yeoman and my humble HTML5 application template

It's already late, it seems. Tools for assembling HTML5 client-side JavaScript applications are now appearing left and right. They're trying really hard to make application development more organized and less stressful. You can now forget such Sisyphean tasks as gathering library dependencies, setting up development environment from scratch and doing endless code-reload-verify cycles. It's all got automated. I'm particularly fond of one of these tools -- that is Yeoman.

Yeoman is a child of Paul Irish, Addy Osmani and many others. This should already tell you the project is interesting. Understandably that's not what gets the job done. One should read the introduction on Yeoman's home page to get a grasp why is it really a great tool (more than a tool). Let me just highlight some key features:

  • Application scaffolding -- Yeoman provides some slightly opinionated application structure via different generators. Default generator, webapp, gives you HTML5 Boilerplate, Twitter Bootstrap and asynchronous JavaScript modules configuration (with Require.js). That's enough to start hacking application prototype.
  • Dependency management for JavaScript libraries via Bower. This allows you to fetch all necessary libraries (like jQuery, Underscore) and frameworks (e.g. Backbone, Angular) using simple command. Updating and removing dependencies is also possible.
  • Automated building for production using Grunt. This includes translation of intermediate languages (CoffeeScript, SASS), concatenation and minification of scripts and style files.
  • Automated test running under headless browser -- Phantom.js. Code linting and other modes of static analysis are supported as well.
  • Development server for your application with auto-reload feature. Changing application code automatically triggers refresh in your browser -- no more window switching and manual reloading. 
Why Yeoman and not X? In my opinion it's the least opinionated tool of all I've evaluated. It gets the job done, doesn't get (much) in my way and allows me to enter its world one step at a time (without steep learning curve).
Although, I'm probably guilty of not using Yeoman as it was intended by its creators...

Enter my application template

I've started using Yeoman just when it was moving from "stable" 0.9 version to new 1.0 milestone. During that time (and probably even now) many generators were somehow broken (uninstallable and outdated). I just couldn't get backbone generator to work. So I used the basic webapp generator to create an application template with some sane defaults. It could probably be "backported" to be a generator in itself. I'd probably get down to it once I'm done with all intermediary tasks.

To be honest I didn't like all defaults, so I've made same changes to better suit my workflow.
The removed parts:
  • Google Analytics -- script was spewing exceptions by default, disabled by commenting out so it's easy to re-enable.
  • Example static content -- it was just an unordered list with template parts.
  • Compass/SASS -- opted for plain CSS, not everyone likes heavy dependencies (Ruby stack) and writing in meta languages.
  • Mocha, Chai -- you have to excuse me, I just prefer other options.

General template additions:
  • Bootstrap from Twitter in pure CSS version -- loaded via @import for both development and production compatibility (it's merged with user stylesheet during build process).
  • QUnit and Sinon -- for unit testing and mocking/stubbing.
  • grunt-contrib-qunit -- for running QUnit tests as a Grunt command.
I've also included very minimal, structured application example to demonstrate rendering external template and embedding it on page. It just shows an indicator of last page load to verify auto-reload is working properly.

Application components handled by Bower:
  • Require.js -- to keep application structure in order.
  • jQuery -- for DOM manipulation and event handling.
  • Lo-Dash -- an improved implementation of Underscore.js utility library.
  • Backbone-AMD -- Require.js-compatible version of Backbone.js framework.
  • Requirejs-tpl -- an extension for Require.js that allows for loading external JavaScript Templates.
  • Marionette -- higher level application framework built upon Backbone.js.
  • Marionette dependencies:
    • Backbone.Wreqr -- messaging infrastructure for module decoupling.
    • Backbone.Eventbinder -- a tidier event binding and clearing mechanism.
    • Backbone.Babysitter -- nested and child views support for Backbone.
Bootstrap JavaScript components are included as well to accompany and enhance its CSS building blocks.
I tried to wire all these up in a way each unwanted dependency can be ripped out without much hassle.

The missing parts:
  • All libraries for building full-featured Backbone/Marionette application are provided but there's no clear sign where to go next. Some simple, neatly structured Marionette example should follow to kick-start development of real world application.
  • QUnit is working with Grunt, Phantom.js and basic test suite. Although no code from main application is loaded nor used in the tests. I have to figure out how to load application modules inside test suite without actually instantiating/launching it. I don't want to just duplicate parts of main.js but use the modules/dependencies configuration from that file automatically. Guess some more advanced Require.js magic needs to happen.

How to start with the template
Ensure you have GitNode.js,  NPM (node package manager) and Yeoman installed -- consult Yeoman documentation for detailed instructions.

  1. Clone my repository or just download a ZIP archive from Github. Go to the cloned directory.
  2. Install system dependencies by running: npm install
  3. Install template components by running: bower install

Basic tools usage
grunt test -- running QUnit tests in a headless Phantom.js environment.
grunt server -- starting development server with auto-reloading capabilities.
grunt / grunt build -- building (optimizing, joining, cleaning) application files for production use.

I hope you have a nice ride with Yeoman and it's accessories! Write me a line if you find my template helpful or you have some suggestions for further development.

No comments:

Post a Comment