Monthly Archives: April 2014

Creating a Backbone, RequireJs and Compass application from scratch with Yeoman

This guide will show you how to scaffold a Backbone + RequireJs + Compass application completely from scratch.

In the way, we are going to cover how to install Node, NPM, RVM, Ruby, Compass and Yeoman (yo, Grunt, Bower). We will cover some of the common pitfalls and how to solve them. This guide assumes you are using a GNU/Linux based operative system and it was tested on Ubuntu 12.04 64 bits.

1. Node.js and NPM

First we install Node.js and Node Package Manager (NPM). It is important to NOT use SUDO when doing this. Using sudo will get you into some nasty permission conflicts. Installing Node and NPM can present some difficulties depending on your machine's setup (firewall, users, etc.) I have found that this Gist has the right solution for most cases. Right now we are going to use the first solution.

We install Node:

echo 'export PATH=$HOME/local/bin:$PATH' >> ~/.bashrc
. ~/.bashrc
mkdir ~/local
mkdir ~/node-latest-install
cd ~/node-latest-install
curl | tar xz --strip-components=1
./configure --prefix=~/local
make install

Then we install NPM:

curl | sh

To verify:

node -v
npm -v

Node should be v0.10.26 or larger, NPM should be 1.4.3 or larger.

2. Compass

With Node and NPM in place, we need to install Compass.

"Compass is an open-source CSS authoring framework which uses the Sass stylesheet language to make writing stylesheets powerful and easy."

To install Compass, we will need Ruby.

If you already have Ruby installed, verify you have the latest version with

ruby -v

And update your ruby gems with

gem update --system

If you don't, we are going to install Ruby (the latest version being 2.1.1). There are different ways to do so, in this case we choose to do it through Ruby Version Manager (RVM).

"RVM is a command-line tool which allows you to easily install, manage, and work with multiple ruby environments from interpreters to sets of gems."

curl -L | bash -s stable
source ~/.rvm/scripts/rvm
rvm install 2.1.1
gem install compass


ruby -v
compass -v

Open a new console, and try ruby -v again. If you don't have the ruby command anymore, you have to enable "Run command as a login shell" on your console's settings. Why this is so is explained in this article.

3. Yeoman

To setup our application, we are going to use the Backbone generator for Yeoman. It will handle most of the hard work for us.

Yeoman is a great tool by Addy Osmani (same guy from the Backbone Fundamentals book) and others, that will help you

"by scaffolding workflows for creating modern webapps, while at the same time mixing in many of the best practices that have evolved within the industry.""

It gives you three tools: yo, for new apps scaffolding, Grunt, to build, preview, test and any other task in your workflow, and Bower, for managing packages and their dependencies.

We install Yeoman (using the -g flag to indicate NPM that the module should be available globally):

Note we don't use SUDO at all when installing with npm!

npm install -g yo

If you see the following output when installing Yeoman:

[Yeoman Doctor] Uh oh, I found potential errors on your machine

[Error] NPM root value is not in your NODE_PATH [info] NODE_PATH = /usr/lib/nodejs:/usr/lib/node_modules:/usr/share/javascript NPM root = ~/local/lib/node_modules

[Fix] Append the NPM root value to your NODE_PATH variable Add this line to your .bashrc export NODE_PATH=$NODE_PATH:~/local/lib/node_modules Or run this command echo "export NODE_PATH=$NODE_PATH:~/local/lib/node_modules" >> ~/.bashrc && source ~/.bashrc

Just follow the instructions in the [Fix] section (if only all CLIs were this helpful!), adding the NPM root to your NODE_PATH.

For scaffolding our Backbone app, we need a Yeoman generator that knows how to do it. Let's install it:

npm install -g generator-backbone

To verify the installation, run

yo -h

You should see a list of generators under the message "Please choose a generator below." Backbone should be there. If it isn't listed, try

echo "export NODE_PATH=$NODE_PATH:~/local/lib/node_modules" >> ~/.bashrc && source ~/.bashrc

Scaffolding our application

We are almost ready. Create a directory for your application, and generate the Backbone app inside it:

mkdir <my-app-name>
cd <my-app-name>
yo backbone

When asked, select Bootstrap for Sass and RequireJs.

[?] What more would you like? 
 ⬢ Bootstrap for Sass
 ⬡ Use CoffeeScript
‣⬢ Use RequireJs

Next we install the project's dependecies:

npm install
bower install

Running our application

Our application is setup. To try it out, run Grunt with the "serve" task:

grunt serve

Our default browser should open at http://localhost:9000/, showing the scaffolded app.

You can see in the console output the different tasks Grunt performed for us (tasks are defined in Gruntfile.js), to get the app up and running. You can see a "connect:livereload" task was run, and a "watch" task is running. This means you can, thanks to LiveReload edit your index.html at /app and the browser will automatically refresh the page with your changes! A huge time-saver.

You can get to work on your Backbone app! The Yeoman generator not only created the app scaffold for us, we can use it to create the basic parts of any Backbone app (models, views, etc.), for instance the router:

yo backbone:router ''

Happy coding!