Extending Bootstrap (2014)
Chapter 5. Compiling Your Styles with Grunt
In this chapter, you will be introduced to Grunt, a task-runner for Node.js. You will learn how to install Grunt, how to use it to compile your LESS files, how to configure the watch plugin to watch your files for changes, and how to set up automatic reloading in your browser.
Why build LESS files with Grunt?
So far, you have compiled your LESS files by hand with Twitter's RECESS. This works fine, but there is a far more efficient way to compile your styles. You can use Grunt and its plugins to automate the compilation of your styles. The following are the benefits of Grunt:
· Easy to install and configure: Grunt is easily installed through Node Package Manager (NPM) and its configuration file is a JavaScript file, so it is easy to configure it to do more when necessary.
· A single configuration for the whole team: You can add the Grunt configuration file, Gruntfile (and the NPM dependency manifest, package.json), to your repository to share your Grunt stack with everyone on your development team and reduce the required amount of configuration for everyone.
· Automatic compilation: With Grunt and its Watch plugin, you can set up watching for your LESS files and make Grunt run the compilation task when it notices a change in the file.
· Live reloading: Grunt's Watch plugin now also features a built-in live-reload server (since v5.x), so you can even make your browser refresh the page when Grunt has recompiled your styles.
· Can be used for all kind of tasks: Grunt is a task runner with over 2000 plugins written by talented people. It can be used for many other things than just the compilation of LESS; for example, minifying of scripts, running tests, optimizing of images, and much more.
Using Grunt to build your project
Now that you know why you should use Grunt, it is time to install it. Let us start with a very simple configuration and expand from there. To do so, perform the following steps:
1. You should already have Node.js installed, so you can use NPM to install Grunt by running the following command in your project root (if not, refer to Chapter 4, LESS is More, for instructions on installing Node.js):
2. sudo npm install –g grunt-cli
3. This will install the Grunt command-line utility globally on your system. In case you already have it installed, you can skip this step.
4. Run the following commands to initialize NPM for your project and install Grunt:
5. sudo npm init
6. npm install grunt –-save-dev
Tip
Appending the --save-dev flag to the command adds the plugin as a project development dependency in package.json (if you have one).
7. Next, you need to install the LESS plugin to be able to compile your styles. You can do that by running the following command in your project root:
8. npm install grunt-contrib-less –-save-dev
9. You have installed everything that you need for now. So, you are ready to create your first Grunt configuration file. Create a new JavaScript file called Gruntfile.js in your project folder and add the following contents:
10.module.exports = function (grunt) {
11. // Grunt configuration
12. grunt.initConfig({
13. less: {
14. app: {
15. files: {"less/main.less": "css/main.css"}
16. }
17. }
18. });
19.
20. // Load plugins
21. grunt.loadNpmTasks("grunt-contrib-less");
};
22. This configuration file consists of two sections: the actual configuration and loading of a single task. The initConfig method allows you to pass parameters to Grunt plugins. In this example, we define a subtask for the less plugin called app, which compiles the styles for your application.
Tip
For more information on the LESS plugin, refer to its documentation at https://github.com/gruntjs/grunt-contrib-less.
23. Now that you have a configuration file for Grunt, you can use it to compile your styles by running the following command:
24.grunt less:app
This will do pretty much the same as running RECESS to compile your styles except now that you are using Grunt, you can automate the compilation. That is what you will do next.
Now that you have Grunt up and running, you can start unlocking some of its true power and configure it to automatically compile your styles when it notices that they have changed. To do so, perform the following steps:
1. First you need to install the watch plugin by running the following command:
2. npm install grunt-contrib-watch –-save-dev
3. Replace the contents of Gruntfile with the following:
4. module.exports = function (grunt) {
5. // Grunt configuration
6. grunt.initConfig({
7. less: {
8. app: {
9. files: {"css/main.css": "less/main.less"}
10. }
11. },
12. watch: {
13. styles: {
14. files: ["less/**/*.less"],
15. tasks: ["less:app"],
16. options: {spawn: false}
17. }
18. }
19. });
20.
21. // Load plugins
22. grunt.loadNpmTasks("grunt-contrib-less");
23. grunt.loadNpmTasks("grunt-contrib-watch");
};
24. The new configuration does not differ much from the previous one, but it registers and adds a subtask for the watch plugin called styles, which watches all LESS files recursively within the less directory and runs the less:app subtask if it notices a change.
Tip
Setting the spawn option to false prevents the watch plugin from running its tasks in child processes, which will speed up the reaction time of the plugin considerably. It will also allow all other tasks of the watch plugin to share the same context.
For more information on the Watch plugin, refer to its documentation at https://github.com/gruntjs/grunt-contrib-watch.
25. Run the following command to make Grunt watch your LESS files:
26.grunt watch:styles
27. When you now make a change in one of your LESS files, you should see something similar to the following output in your command prompt:
28.$ grunt watch:styles
29.Running "watch:styles" (watch) task
30.Waiting...OK
31.>> File "less/main.less" changed.
32.Running "less/app" (less) task
33.File css/main.css created.
34.Running "watch:styles" (watch) task
35.Completed in 0.648s at Thu Jan 02 2014 13:06:57 GMT+0000 (UTC) - Waiting...
36. As you can see, the less:app subtask is now automatically run when main.less (or any other LESS file in the less directory) is changed.
Tip
If you are using Linux, you can install GNU Screen to run Grunt in the background. For more information about using GNU Screen, refer to its documentation at https://wiki.archlinux.org/index.php/GNU_Screen.
So far, you have configured Grunt to both compile and watch your LESS files. Would it not be nice if you could see the changes live in the browser as you make them? With Grunt, this is possible; it is called live reloading, which is what we will set up next.
Using Grunt for live reloading
So far you have configured Grunt to both compile and watch your LESS files. Now it is time to make it refresh your browser window when the watch plugin notices a change. To do so, perform the following steps:
1. Open up Gruntfile and add the livereload option to the watch plugin configuration with the help of the following code:
2. watch: {
3. styles: {
4. files: ["less/**/*.less"],
5. tasks: ["less:app"],
6. options: {
7. livereload: true,
8. spawn: false
9. }
10. }
}
11. This option will tell the watch plugin to start a live-reload server on the default port (35729).
Tip
You can also start the live-reload server on a different port by giving the livereload option a numeric value instead, for example, livereload: 1337. This is useful if you want to run multiple live-reload servers on the same machine.
12. Next, you need open up your index.html file and add the following script tag right before the closing body tag:
<script src="http://localhost:35729/livereload.js"></script>
13. This will connect your browser to your live-reload server and allow you to reload the page when you change a file that is watched.
Tip
There are also other options for setting up live reloading, such as using browser extensions and the Connect plugin. For more information, refer to the Live Reloading section in the Watch plugin documentation at https://github.com/gruntjs/grunt-contrib-watch.
Now restart Grunt, navigate to your project root with your browser, change any of your LESS files, and save it. When you do so, your browser should be automatically refreshed.
Summary
You have now learned how to install Grunt and how to automate the compilation of your styles. You also learned why you should use Grunt and what you can do with it, besides compiling your LESS files.
In this chapter, you replaced RECESS with Grunt in your project and used it to compile your styles, watch your LESS files, and reload your browser when a change is made to any LESS file.
In the next chapter, you will learn to adapt Bootstrap JavaScript plugins to suit your needs. Even though the plugins might not seem that useful at first, they can be customized to do more.