Grunt Front-End Workflow/Boilerplate
What is it?
The Grunt Front-End Workflow/Boilerplate started as Backbone/RequireJS Multipage Boilerplate. Since its initial release, it has evolved into a structured, modular and test-driven front-end development & build workflow with Grunt task runner. It suggests certain tools and methodologies and includes some boilerplate code. See the related blog post: http://www.akikoo.org/log/2013/05/26/front-end-workflow-with-grunt/.
It supports both SPAs (single page applications) and more traditional multi-page setups, managing dependencies with RequireJS (http://requirejs.org/).
For stylesheets, have a look at One Web Boilerplate (http://akikoo.github.io/one-web-boilerplate/) that uses Sass preprocessor (http://sass-lang.com/) and Compass (http://compass-style.org/), with SMACSS (Scalable and Modular Architecture for CSS, http://smacss.com/) and some OOCSS (Object-Oriented CSS, http://oocss.org/). You can just drop the whole /webroot/assets/scss directory from One Web Boilerplate into /www directory in Grunt Front-End Workflow and it will work, with only one small path change in /scss/common/_base.scss:
@import "../../assets/css/common/normalize.css"; to this:
The goal of this workflow is to support modularity and code reuse by organizing code into both common and page-specific packages. RequireJS setup is adapted from https://github.com/requirejs/example-multipage-shim.
Grunt is used for running specified tasks during development. It's also used for creating builds.
###Currently the following common tasks are included:
- Compile modular html patterns (you can use variables and pass in data too),
- Compile AMD based modules using RequireJS,
- Watch/compile Sass/Compass modules into CSS,
- Watch/lint CSS/JS code,
- Optimize images,
- Generate sharp vector icons to all devices,
- Generate dynamic build headers
- Generate YUIdoc documentation, and
- Run unit tests in different browsers.
You'll need the following tools to get the full advantages of this workflow:
###Ruby On OS X, you'll already have Ruby installed. On Windows, see http://rubyinstaller.org/downloads/.
###Sass and Compass
Make sure you have Ruby installed before this step.
Install Sass: http://sass-lang.com/tutorial.html.
Install Compass: http://compass-style.org/install/.
###Node.js Install Node.js with npm (package manager for Node): http://nodejs.org/.
Install Bower front-end package manager (http://bower.io/).
npm install -g bower
Bower currently has some issues on Windows so you might want to skip the next step. Packages that Bower installs are already included in this repository.
However if Bower works in your environment you'll probably want to manage your front-end library packages with it. To do so (after installing bower globally), go to the project folder and install/update packages using the dependencies listed in the current directory's bower.json.
By default, Express application framework and MongoDB are used for persisting models with REST API. For installing MongoDB, see http://docs.mongodb.org/manual/installation/. If you're on OS X, see http://www.mkyong.com/mongodb/how-to-install-mongodb-on-mac-os-x/.
In this project there's also a PHP REST API in /api directory (using Slim framework),
and a MySQL database dump
itemdb.sql if you want to use those for prototyping.
I've recently switched to using the Express RESTful server and MongoDB instead.
Be sure to check the links above, to install the correct MongoDB version for your environment. On OS X, this worked for me using the terminal:
## Go to temp folder cd Downloads/ ## Download MongoDB curl http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.4.6.tgz > mongodb.tgz ## Extract it tar -zxvf mongodb.tgz ## Move to generic location mv -n mongodb-osx-x86_64-2.4.6/ /usr/local/mongodb ## Create data dir and fix permissions sudo mkdir -p /data/db sudo chown `id -u` /data/db ## Assign $PATH environment variables in .profile or .bash_profile export MONGO_PATH=/usr/local/mongodb export PATH=$PATH:$MONGO_PATH/bin ## Try it mongo -version ## Start the mongod process mongod ## Open the mongo shell (in second terminal tab/window) mongo
If you don't need a local RESTful API or database, or if you use other service, comment out this line in Gruntfile.js (line number 76):
// server: path.resolve('./server.js'),
Remember also to adapt the service URL in /www/js/app/collections/items.js if necessary.
###Grunt See http://gruntjs.com/getting-started.
npm uninstall -g grunt npm install -g grunt-cli
After installing grunt-cli (Grunt's command line interface) globally, go to the project folder and install all the dependencies listed in package.json. This will install a local version of Grunt as well.
To start developing, go to the project folder in your terminal and run
Note that if you installed MongoDB as mentioned above, you need to start the service by first starting the mongod process in terminal:
Then, open the mongo shell:
Then go to http://localhost:9001/ to view your site. You can also access your
local site from another device on the same LAN by using your IP address instead
localhost, for example http://10.0.0.32:9001/. Files are being observed
for changes using livereload so you don't need to refresh the page manually.
To trigger the optimized build, go to the project folder and run
This will run all the tasks again and copy the optimized files to
directory, ready for deployment. You also get YUIDoc documentation generated from
For details about all the tasks and processes, see documentation in Gruntfile: https://github.com/akikoo/grunt-frontend-workflow/blob/master/Gruntfile.js, and other files.
Be sure to exclude
from version control. You should probably exclude
/www/js/lib as well because
third-party libraries are managed locally by Bower.
I hope this framework is as useful to you as it is for me. Have fun!