Getting started overview

The Backbone Boilerplate has been designed and implemented for small to medium sized projects. It started as a boilerplate and has since evolved into a robust development environment. Be that as it may, this is not an enterprise framework. Essentially if your application starts to exceed 1MB in source (after optimizations), you will likely need to extend the defaults to accommodate.

This is the product of significant research and frustration. Developers who have tried to configure RequireJS will appreciate the elegance of the integration. While other boilerplates for Backbone.js exist, they may:

• Modify library source code.
• Not have a build system.
• Not have example applications written utilizing it.
• Impose far too much on your structure.

Project breakdown

The Backbone Boilerplate project contains the entire boilerplate including all default configuration files necessary to power the build tool. It is entirely possible to run the Boilerplate without a server (as would be recommended for any Phonegap application). More on that is discussed in the Filesystem section.

BBB stands for [B]ackbone [B]oilerplate [B]uild and is the tool used for building the assets and serving the Backbone Boilerplate project locally. This tool is built upon Grunt for the build platform. This provides an excellent foundation and the possibility of extending with any future Grunt plugins. This tool requires Node.js and can be installed following the Installation instructions.

Whats included?

This project is built upon the hard work provided by the open source community. Design decisions change frequently as this is a rapidly evolving field, this means bundled libraries are subject to change.

Third-party JavaScript

Web application development:

• jQuery - (DOM manip, AJAX, etc)
• Lo-Dash - (Functional utilities)
• Backbone.js - (Application structure)

Module management:

• RequireJS - (Development module loader)
• Almond - (Production module loader)

Third-party CSS

• H5BP - (Sane web application default styles)

Filesystem structure

The structure is fairly straightforward. Application code, Stylesheets, and templates are placed inside the app/ directory.

Third-party static assets go into the vendor/ directory. After you install Backbone Boilerplate you'll have a folder vendor/bower which is where all bower packages are installed.

The test/ directory contains a configuration suitable for running QUnit, Mocha, or Jasmine tests.

.
├── app
│   ├── img
│   ├── modules
│   ├── templates
│   ├── styles
│   │   └── index.css
│   ├── app.js
│   ├── config.js
│   ├── main.js
│   └── router.js
├── test
│   ├── jasmine
│   │   └── specs
│   ├── mocha
│   │   └── specs
│   └── qunit
│       └── specs
└── vendor
    └── bower
        ├── almond
        ├── backbone
        ├── chai
        ├── html5-boilerplate
        ├── jasmine
        ├── jquery
        ├── lodash
        ├── mocha
        ├── qunit
        ├── requirejs
        └── sinon
├── .bowerrc
├── .gitignore
├── .travis.yml
├── bower.json
├── CONTRIBUTING.md
├── favicon.ico
├── Gruntfile.js
├── index.html
├── LICENSE
├── package.json
└── README.md

Files

These are files within the Backbone Boilerplate that hold special significance to the project.

Directory: Application app/

app.js

Load all application-wide logic inside this file. This is loaded before any other script in the application except for app/main.js. This module will return a single object called app.

Use this file to add/configure plugins, add global app variables, and when you need to change your template configuration.

config.js

This is one of the two configuration files. This is a RequireJS configuration file and you can read up more on the options. You will mostly use this file for updating your dependencies or adding new folder paths. More information can be found in the Modules (RequireJS) section.

main.js

This file serves as the entry point into the application. It sets up the application and initializes the Router.

This file runs immediately after RequireJS is loaded on the page.

router.js

This file is your main application router. Regardless if you use sub-routers or not, you should wire up your application state here.

Directory: Stylesheets app/styles/

index.css

Since CSS doesn't have a module loader plugin like RequireJS, its not particularly easy to get files in without modifying index.html. This project leverages @import statements to dynamically fetch stylesheets. Whenever you add or remove a stylesheet, make sure its updated here.

Directory: Third-party assets vendor/

All third-party javascript and stylesheets should be added within this directory. Stylesheets can be loaded using the @import statement within app/styles/index.css. Load JavaScript through RequireJS by updating the paths configuration to point to the dependency's distribution. Determine if the library is AMD compatible. If it is not, you will need to shim it.

Directory: Root /

index.html

Is your single point of entry to the application and since HTML5 pushState is enabled all 404 requests will automatically forward to this page to enable client side routing.

You'll notice some odd looking comments in this file that look something like:

<!-- build:[src] /source.min.js --> and <!-- /build -->

These are used during build time to specify what file path to use. This happens for both the source and the styles. The value inside of the [] is the attribute to change, and the following value is the replacement. This allows us to not require a template or specific server to test your code. You can use any server with Backbone Boilerplate hassle-free, just point to the directory and disable pushState (unless your server is configured to support it).

Gruntfile.js

The Gruntfile is the heart of the build system. The original Backbone Boilerplate was built along side Grunt and was able to influence early development of tasks. It has since become an industry standard and Backbone Boilerplate is compatible with the latest version. All of the tasks have associated documentation can be looked up if the defaults don't work for you.