A boilerplate for a front-end build system setup using requirejs, bower, gruntjs and of course LESS

You must have nodejs installed in order to use this tool. http://nodejs.org/

Lets get started:

cd build

npm install

You can trigger the file watcher using the following command: (assuming you're in the build folder)

grunt watch

Once the file watcher is initiated it will watch both assets/js and assets/css folders for any changes. Meaning if you change or add any files inside either of those folders, it will run the build tools and output the compiled file(s) in the respective /dist subfolder.

Since the LESS compiler is fairly straight foward. lets talk a bit more about the JS compiler.

lets take a look at /assets/js/config.js

requirejs.config({
    baseUrl: '/assets/js/',
    waitSeconds: 0,
    paths: {
        jquery: '../../build/bower_components/jquery/dist/jquery',
        parsleyjs: '../../build/bower_components/parsleyjs/dist/parsley',
        site: 'app/site'
    },
    shim: {
        site: ['jquery']
    },
    packages: [

    ]
});

This is our config file which we use to keep track of dependencies and other assets.

This is where bower comes into play. Using bower install we can safely generate new libs and plugins into our folder structure as well as automatically add them to our config file.

For example, lets cd to our build folder and run bower install colorbox

The file watcher will recognize these changes and update the config file to look like this.

requirejs.config({
    baseUrl: '/assets/js/',
    waitSeconds: 0,
    paths: {
        jquery: '../../build/bower_components/jquery/dist/jquery',
        parsleyjs: '../../build/bower_components/parsleyjs/dist/parsley',
        site: 'app/site',
        colorbox: '../../build/bower_components/colorbox/jquery.colorbox',
    },
    shim: {
        site: [
            'jquery'
        ]
    },
    packages: [

    ]
});

Now that we've updated our config.js we need to tell the build tool which assets we're going to include in our production file. This is pretty simple and we do it inside of /assets/js/main.js which looks like this.

require(['./config'], function(){
    require([
        'parsleyjs',
        'colorbox',
        'site']);
});

Notice that I'm not including jquery, even though it's required for both colorbox, and /app/site.js. We don't need to do this inside of main.js because we're already defining it inside of config.js. This allows us to define dependencies for our plugins/files using:

  shim: {
site: [
'jquery'
]
},

Assuming that the changes you make are error free, and you save /assets/js/main.js your production ready js file will be placed inside /assets/js/dist/

So we've now covered how we can manage our JS assets and get them ready for production. Lets talk about how we can troubleshoot/debug any issues we run into along the way.

below I've provided a very basic php conditional script that looks for a querysting yourdomain.com/?dev.

$url = 'http://' . $_SERVER['SERVER_NAME'] . $_SERVER['REQUEST_URI'];
if(false !== strpos($url,'dev')) { 
<script data-main="assets/js/main.js"  src="assets/js/require.min.js"></script>
} else {
<script src="assets/js/require.min.js"></script>
<script src="assets/js/dist/main.min.js?v=1"></script>
}

By using the data-main attribute inside of the require.min.js script tag and pointing it to the main.js file, requirejs will load each dependency individually.

<script data-main="assets/js/main.js"  src="assets/js/require.min.js"></script>

Having each script load individually will make it much easier to pin point any errors being returned

I've setup a JS unit testing folder, which can be found here: /tests/. Inside of this folder, we can add unit tests using the popular unit testing framework qunit. These tests will run in the headless browser phantom.js and can be initiated by using grunt watch or grunt test.

If you end up using grunt watch for unit tesing, it will watch the /tests folder and re-run the unit tests upon any change.

I've created a number of other commands that mimick the watcher, to help troubleshoot, or get a different output.

To compile your LESS into unminfied css, run:

grunt less:dev

To compile your LESS like the watcher, run:

grunt less:prod

To compile your JS like the watcher, run:

grunt buildjs

To update your config.js file with any new bower updates without the watcher, run:

grunt package

To run unit tests via the /tests/ folder, run:

grunt test

You can make edits to the watcher, and other grunt processes via

/build/gruntfile.js

For windows users, I've also included batch files inside of /build that run the node commands.

For those not to fimilar with bower, try checking out their package list.

http://bower.io/search/