Handy Little Tasks

---

This chapter’s purpose is to get the reader further into Gulp. We’ll do this by showing small snippets of code and usage of everyday tasks that a developer might need.

Script translation

During the past years, the web has seen an incredible increase in the usage of JavaScript. In the beginning, it was merely used to respond to some click event to toggle the visibility of some HTML element like a picture. Nowadays, it is no exception to see web applications with thousands of lines of JavaScript code, performing a bunch of tasks in the browser instead of posting back everything to the server and waiting for an answer. So-called Singe Page Applications (SPA) have seen an increase in popularity. It comes with a downside though: complexity can become very tough and small mistakes are easily made. As such, we also see a growing number of tools and languages that transpile the code you write in them into JavaScript. Normally this is a manual task that might become tedious after a while. Luckily we are making use of gulp.js, which makes life easier by automating things.

Note: Transpiling is a specific term used to indicate the process of transforming one language into another one while keeping the same level of abstraction—basically going from CoffeeScript, TypeScript…to JavaScript. Compiling is going from one language and transforming it into something else, like compiling C# into binary code (IL in this case).

CoffeeScript

CoffeeScript was likely the first language I encountered that would generate JavaScript after translation. However, if you have a bunch of files, and several are changed, it would mean translating them one by one. Not anymore with Gulp. There’s a simple plugin available for it, which we can use in our gulp tasks or watchers.

Code Listing 23: Fibonaci in CoffeeScript – /Assets/Coffee/fibonacci.coffee

The sample is the well known Fibonacci sequence, which we would like to be translated into JavaScript.

Create a new gulpfile.js directly under the Fibonacci folder, and run the following commands:

• npm init (This will generate the package.json file after you go through the wizard.)
• npm install gulp --save-dev
• npm install gulp-coffee --save-dev

In the gulpfile.js file, enter the following:

Code Listing 24: gulpfile.js for CoffeeScript demo - /gulpfile.js

In a terminal window or DOS box, run the default Gulp task, which will output the following JavaScript file under the wwwroot/scripts folder as expected (as specified as parameter for gulp.dest):

Code Listing 25: fibonacci.js - /wwwroot/scripts/fibonacci.js

If you do not like this style of output, then you can pass in a parameter to the coffee call, like .pipe(coffee({ bare:true})). 

This will then compile the fibonacci.coffee file into the following JavaScript code:

Code Listing 26: fibonacci.js with bare : true - /wwwroot/scripts/fibonacci.js

Some handling when an error occurs

Exceptions do happen, so it is better to keep them in mind and act appropriately if needed. After all, an exception might break your entire Gulp script, and Gulp plugins might respond to erroneous events.

For example, say you want to put some comment in the CoffeeScript file as a small note to yourself of what the code is supposed to do. You might write /* some comment */ in the file. That is perfectly fine in JavaScript, but the CoffeeScript compiler returns an error when performing its magic.

To make the code in Code Listing 24 more robust, we can change it to:

Code Listing 27: gulpfile.js with error event listener - /gulpfile.js

Now open the fibonacci.coffee file. On top, write /* Fibonacci sequence */ and run the default Gulp task again. We will see the following output:

Figure 23: When something goes wrong and we would like to get notified

The output of the gulp-coffee plugin now shows nicely where it goes wrong so you can quickly find out and solve the problem.

TypeScript

TypeScript is a language developed by Microsoft, and just like CoffeeScript, compiles to JavaScript. It is gaining a lot of interest and momentum nowadays since the Angular.js team over at Google announced a close collaboration. TypeScript has been chosen as the go-to language to write an upcoming Angular.js-based application. As you can sense already, this will be big in the coming years.

If you want to know more about TypeScript, I suggest you take a look at this website, especially the Playground section to see it at work. The example being used here is one of them.

Code Listing 28: inheritance.ts - /Assets/TypeScript/inheritance.ts

There are several plugins available to compile TypeScript to JavaScript. I opted for gulp-typescript-compiler, but you can try out any of the others.

Code Listing 29: gulpfile.js for compiling TypeScript - /gulpfile.js

This results in the following EcmaScript 5 code:

Code Listing 30: Compiled JavaScript - /wwwroot/js/inheritance.js

Wow, I bet you didn’t want to write that yourself. You can also pass in options in the ts call. Be sure to check them out and play around with them to see what works for you, like sourcemap generation, for example:

Code Listing 31: gulpfile.js for compiling TypeScript with options - /gulpfile.js

This will generate a sourcemap file with the name inheritance.js.map in the output folder wwwroot/js. It will also add the following line at the bottom of the generated inheritance.js file to indicate the relationship between both: //# sourceMappingURL=inheritance.js.map.

EcmaScript 6

EcmaScript 6 (ES6) is the new, upcoming version of JavaScript. Since it is so new, most browsers do not support it yet (or at least not fully). That’s a pity, as the things you can start doing with it are pretty awesome. Luckily for developers, there is already a way to make use of it and then transpile it to EcmaScript, 5 which current browsers understand all too well. One example is making use of classes and inheritance—something JavaScript as we knew it wasn’t particularly good at. Take the following ES6 sample:

Code Listing 32: ES6 file inheritance.js - /Assets/ES6/inheritance.js

It has a class Shape, which has a move function. Two other classes, Circle and Rectangle, inherit from it. After the class declarations, there are four more lines, which instantiate a new Circle object and pass in some parameters to its constructor, which calls in its turn the base class constructor as well via the super() call. To see the object itself, we write it to the console. Then we move the circle object to some new x:y coordinates and write it again to the console. Hey, this might be the start of a fun new game!

To transpile it to ES5, however, we need some help. There is at the time of writing a Gulp plugin, and likely more are soon to follow once ES6 takes off. Our Gulp file will look like this:

Code Listing 33: gulpfile.js - /gulpfile.js

Note: Before you run the gulp task, make sure you have the gulp and gulp-es6-transpiler packages installed.

The ES5 equivalent will be generated into the following code. For the faint of heart, perhaps take a look at the next paragraph instead, as it is not pretty.

Code Listing 34: ES5 file inheritance.js of transpiling our ES6 inheritance.js file - /wwwroot/js/inheritance.js

Indeed, the ES6 style of writing that is much easier on the eyes.

To test this transpiled file quickly in a browser, you can open jsfiddle.net, paste the code in the JavaScript pane, and run it. Open the F12 tools of your favorite browser and take a look at the Console. The following screenshot shows the outcome of the code:

Figure 24: Both Circle objects before and after the move function call

Source maps

Source maps are a handy way to make a browser aware of where the original files were for a certain resource like a JavaScript or CSS file. We already saw a glimpse of it being used earlier in this chapter under the TypeScript paragraph. There, it was an optional setting. Not every Gulp plugin, however, has this out of the box. Luckily, there is a dedicated Gulp plugin available to inject into the stream. Actually, as we will see in a moment, it takes two points into the stream: one that does the initialization, and another that does the writing.

We are going to make use of Sass for this example; be sure to use npm install to get the gulp-sass package. Just like Less, this is a popular CSS precompiler syntax that is gaining more popularity. The next version of the famous Bootstrap library, for example, will be written with Sass, while the current version makes use of Less. Note that Sass files have the extension .scss. To make yourself familiar with the syntax of Sass, I encourage you to take a look at this guide.

Code Listing 35: Styles.scss - /Assets/Sass/styles.scss

Code Listing 36: gulpfile.js - /gulpfile.js

This code listing does quite a bit, so let us examine the css task a bit closer. First, all Sass files are put into the stream. Then the sourcemap gets initialized. You can put this after the Sass pipe, but it is recommended to put it before. Then the compilation of Sass into CSS performs its magic and the sourcemap gets written. In the current call, the mapping will be written in the resulting CSS file, like the following:

Code Listing 37: Styles.css with sourcemapping included in the file itself - /wwwroot/css/styles.css

This works, but personally I like to keep the mapping in a separate file. This can be done quite easily by just changing the call to the write function like the following:

Code Listing 38: Adjusted gulpfile.js to write the sourcemap to another file – gulpfile.js

After running the default Gulp task, this time another subfolder will be created, maps, which will hold the generated sourcemap file like this:

Figure 25: Styles.css and its corresponding Styles.css.map file

Unlike with the inline mapping before, in Styles.css the separate Styles.css.map file looks somewhat different. Also, the Styles.css now only holds a short indication as to where the browser can find the mapping file.

Code Listing 39: Styles.css.map - /wwwroot/maps/styles.css.map

Note: The sourcemap file might look a bit different on your machine. Here you see \n, which is return and newline on Mac OS X, while on Windows it will show \r\n instead. Also, the order of the properties of the json file might be different, but essentially the same information will be in there.

Code Listing 40: Styles.css - /wwwroot/css/styles.css

To test this in the browser, add an HTML file under the wwwroot folder with the following content:

Code Listing 41: index.html - /wwwroot/index.html

The output on the screen will come as no surprise. The interesting part happens when you open the so-called F12 tools of your browser. Open the Resource pane and see the mapping being made. Note that every browser differs a bit in showing it, however.

Safari:

Figure 26: Sourcemaps in Safari

Chrome:

Figure 27: Sourcemaps in Chrome

Note that source mapping does not only apply to CSS, but can also be used for JavaScript files compiled or transpiled from another source file. Browsers can make use of this to show where some code came from originally. We already saw a sample of JavaScript source maps previously in the TypeScript section.

Restoring order

Loading in files to be processed by a specific task is what Gulp makes a great tool. These files are being loaded in the same order they are in the folder. That means that if you have files which need to be outputted in a certain order in the resulting file, you will have to do some manipulation. A situation where this might occur is the concatenation of a bunch of CSS files. The order is very important in such a file, as it might make your application look different from what you intended.

Take the following three small .css files and Gulp file:

Code Listing 42: /Assets/css/anotherstylewhichshouldbeattheend.css

Code Listing 43: /Assets/css/something.css

Code Listing 44: /Assets/css/styles.css

Code Listing 45: /gulpfile.js

We have introduced here another Gulp plugin: gulp-concat. Be sure to have it installed it before running the gulp command. What it does is concatenate the stream into one file, all.css files in this particular case. This makes it very easy to bundle scripts together and reduces the number of files the browser needs to fetch.

The output of running the default Gulp task will result in the following all.css file:

Code Listing 46: /wwwroot/css/all.css

This is not exactly what we want, as the style which makes the div borders red should become the last in the file. We can do this in different ways; let us investigate just how.

Ordering via gulp.src

This is a pretty simple approach, as you do not have to get another Gulp plugin. Actually, it is already in your code as gulp.src. Instead of simply filling in a glob like ./Assets/less/**/*.less to grab all the Less files under Assets/less and its subfolders, it is possible to make an array with the order of the files you want them in. Let us take the following example:

Code Listing 47: gulpfile.js with ordering in gulp.src - /gulpfile.js

Be sure to have installed the packages gulp, gulp-concat, and gulp-order.

The output will now become the following after running the default Gulp task:

Code Listing 48: /wwwroot/css/all.css

The styles.css file was put as first in the ordering, and while keeping the rest of the files in order of filename in the folder, the all.css file gets generated.

Ordering with gulp-order

Even though ordering via gulp.src works out, it makes it prone to change, and actually does two things: fetching files and ordering them. That is not always desired from a separation of concerns point of view. As such, it is better to make use of a dedicated Gulp plugin: gulp-order, which gets introduced in the following changed Gulp file.

Code Listing 49: gulpfile.js with ordering via the gulp-order plugin

The output is the same, as in Code Listing 48.

Logging

Gulp.js is a task runner, which means it does all its magic behind closed doors. You do not have real visual feedback like when opening a browser and navigating to some page. At best, you get some default output to a console window of what is going on. If you want more information, then you will have to put it in yourself. We will take a look at a few different ways to do this.

console.log

This is the “poor man’s” way of logging, and it works without having to install some fancy plugin. In former chapters, we already saw the usage of this, for example, in Code Listing 10.

gulp-util

This handy little plugin does more than just logging, so be sure to check out the documentation for an overview of all the options. It’s capable of making a good old “beep” sound, and it facilitates showing colored messages on the screen. As an example, take a look at the following code:

Code Listing 50: gulpfile.js for gulp-util - /gulpfile.js

I cannot provide the “beep” sound in this book, but the colored output looks like the following:

Figure 28: Colored output with gulp-util

Note: There are not that many colors available. gulp-util makes use of the Chalk npm module. The colors can be found in the following table.

It’s possible to chain these colors together to get another effect. As we saw in the demo gulpfile, underline was concatenated to red, resulting in a red text that was underlined. Note that the underline might not work on your machine, for example, in Windows, as not every terminal in Windows allows for underlined text.

gulp-logger

This is a third logging helping component. Its purpose is to log the progress of the current task for every item in the stream we are providing to it. Take a look at the following Gulp file:

Code Listing 51: gulpfile.js for gulp-logger - /gulpfile.js

Through the means of options, we can manipulate how the gulp-logger module is going to behave. In this example we use only four, but there are more that can come in handy. Be sure to check out the documentation of this component to read about those extra option settings.

The output can be seen in the following figure. Note the colored messages. The colors option is set to true by default. You could turn it off if you wanted to by setting it to false.

Figure 29: Output of the gulp-logger module with extra options set

Cleaning up

Gulp is great at generating output, and overwrites output from before. When setting up a Gulp architecture in your application, you will likely test it on every step. This might end up giving output files in the end which you might not need anymore or, or which just become ballast. Potentially, you might integrate the leftovers in your real-life solution, degrading performance, or worse, cause bugs.

As such, it’s a good practice to start up with a clean slate and clean out the output folder and its subfolders before performing Gulp magic. Usually this is done as a dependent task of the default task like:

gulp.task('default', ['clean','build','watch','connect']);

As we will find out, there are Gulp plugins available for cleaning up. However, this is a good case to show that it’s not always the trivial plugin you want to make use of. The trivial one in this case would be gulp-clean. When we take a look at its documentation, we will see the message:

Deprecated use gulp-rimraf instead!

Ok, following that link, we open the documentation page of gulp-rimraf. There we see the following message:

Deprecated in favor of https://github.com/gulpjs/gulp/blob/master/docs/recipes/delete-files-folder.md

So we end up with the del module from node.js directly. The showcase of this is that even though every day there are new plugins being made for Gulp, there are also existing plugins being removed in favor of better ones. Finding these might be a bit of a challenge in the beginning, but you will soon find the good ones that work out for you.

Using the del module in your Gulp file is easy, as you can see in the following demo, where we have a wwwroot folder with css and js subfolders with files in them.

Figure 30: Project overview before cleaning

We only want to remove the files and their folders under css and js, but not the config.json file, as that might hold important information. We can make an exception while deleting everything by putting a ! in front of the path to exclude the file.

Code Listing 52: gulpfile.js cleaning - /gulpfile.js

Note from this sample that we do not make use of gulp.src as we have seen so many times before. We directly call the del module and pass in an array of paths to delete: all with the exception of the config.json file. After running the default task, we keep the following structure in our project:

 Figure 31: Project after having cleaned out the wwwroot folder

Load plugins dynamically

So far, we have been writing require statements at the top of each of our Gulp files. That list might become pretty long when you’re adding a lot of plugins. For example, the following is not an exception:

Code Listing 53: A lot of require statements - /gulpfile.js

That might even become more cumbersome when you start adding additional plugins. There is, however, an alternative way, one that reduces this listing tremendously by making use of a Gulp plugin. The following listing shows the usage of the gulp-load-plugins plugin.

Code Listing 54: Reducing it to loading plugins lazily - /gulpfile.js

The secret is in the fact that the plugins are known in the package.json file and installed via npm. So when we have the following package.json:

Code Listing 55: /package.json

We can then refactor a gulpfile.js file to make use of the plugins variable:

Code Listing 56: gulpfile.js loading plugins in a lazy fashion - /gulpfile.js

Instead of writing less(), we then write plugins.less() to make it work.

Summary

This chapter covered several small but handy samples, which you can reuse in your own projects. Be sure to play around with the options of each plugin and experiment to see what works out best for your project.