Building your Angular app with Gulp.js

June 20, 2014

As my work has transitioned from traditional web apps to thick-client Javascript apps (primarily using Angular), <a href="http://gruntjs.com">Grunt</a> has become essential in my workflow. Grunt is a nice tool and it gets the job done. But there was always something I didn’t like about it that I couldn’t quite articulate until I discovered <a href="http://gulpjs.com">Gulp.js</a>. Whereas in Grunt, you create a json configuration file, Gulp is just a script. It’s code. And it really fits my programmer brain better. In this post, I’ll convert a basic Gruntfile that compiles and minifies Coffeescript into Gulp. <h3 id="the-original-gruntfile">The Original Gruntfile</h3> The original Gulpfile I’m converting can be found <a href="https://github.com/adamalbrecht/ngQuickDate/blob/48fb6f6db38de16d5c92bbbbe5e8e0eee2ad69b0/Gruntfile.js">here</a>. It is for an angular datepicker library that I wrote called ngQuickDate. (Side note: I’m in the middle of re-writing this library from the ground up because I no longer like the way it works). I won’t put the entire file inline, but here are the relevant parts that compile coffeescript files and then minifies them. <div class="highlight"><pre class="highlight javascript"><code>coffee: { compile: { files: { "spec/build/specs.js": ["spec/*.coffee"], "dist/ng-quick-date.js": ["src/*.coffee"] } } }, uglify: { my_target: { files: { "dist/ng-quick-date.min.js": "dist/ng-quick-date.js" } } } // ... grunt.loadNpmTasks('grunt-contrib-coffee'); grunt.loadNpmTasks('grunt-contrib-uglify'); grunt.registerTask('default', ['coffee', 'uglify']); </code></pre></div> It’s pretty straightforward, but I have 2 problems with it. First, my 2 tasks have no knowledge of one another. Coffeescript files are read, compiled, and written to disk. Then another task reads these new files in, minifies them, then writes to disk again. My second problem is that, with a configuration-based approach like this, it is very hard for a beginner to figure out how to modify tasks and add additional logic to them. So let’s first reproduce the same gruntfile in Gulp. <h3 id="simple-gulpfile">Simple Gulpfile</h3> <div class="highlight"><pre class="highlight javascript"><code>var gulp = require("gulp"); var concat = require("gulp-concat"); var coffee = require("gulp-coffee"); var uglify = require("gulp-uglify"); var rename = require("gulp-rename"); gulp.task("js", function() { gulp.src(["src/*.coffee"]) // Read the files .pipe( coffee({bare:true}) // Compile coffeescript .on("error", gutil.log) ) .pipe(concat("ng-quick-date.js")) // Combine into 1 file .pipe(gulp.dest("dist")) // Write non-minified to disk .pipe(uglify()) // Minify .pipe(rename({extname: ".min.js"})) // Rename to ng-quick-date.min.js .pipe(gulp.dest("dist")) // Write minified to disk }); gulp.task("default", function() { gulp.start("js"); }); </code></pre></div> While it’s not any shorter, I find it significantly easier to read and modify without referring to documenation. As you can see, Gulp accomplishes tasks by using streams and piping, which is a great fit for reading source files, performing a number of actions on them, then writing back out to disk. Each action is chained on to the last one and this makes it unecessary to write out to temp files, thus making it quite a bit faster, as well. <h3 id="angular-extras-in-gulp">Angular Extras in Gulp</h3> If you’ve used Angular for any significant period of time, you’ll know that it’s a bit quirky. First, minification often breaks your app due to the way its dependency injection system works. But luckily there’s a fix for this: <a href="https://github.com/btford/ngmin">ng-min</a>. This library will analyze your source code and add the necessary arrays around function calls to make it minification friendly. For example, it will convert this: <div class="highlight"><pre class="highlight javascript"><code>angular.module('whatever').controller('MyCtrl', function ($scope, $http) { ... }); </code></pre></div> into…. <div class="highlight"><pre class="highlight javascript"><code>angular.module('whatever').controller('MyCtrl', ['$scope', '$http', function ($scope, $http) { ... }]); </code></pre></div> Integrating this into Grunt is easy enough, but you have to do so as an entirely separate task that runs independently of your compilation and minification. In gulp, we can add it into the middle of our chain of compilation/minification actions by adding a couple lines to our Gulpfile: <div class="highlight"><pre class="highlight javascript"><code>var ngmin = require("gulp-ngmin"); // NEW // ... .pipe( coffee({bare:true}) .on("error", gutil.log) ) .pipe(ngmin()) // NEW: Make angular code friendly to minification .pipe(concat("ng-quick-date.js")) // ... </code></pre></div> Couldn’t be easier. Next, let’s say we’re also compiling html templates from Jade but we’d like them to pre-load them into Angular’s template cache so we don’t have to make http requests every time. No problem! <div class="highlight"><pre class="highlight javascript"><code>var ngmin = require("gulp-angular-templatecache"); // ... gulp.src(["src/templates/*.jade"]) .pipe(jade()) // Compile from jade to html .pipe(templateCache()) // Convert to JS strings and place in Angular template cache .pipe(gulp.dest("dist")) // Write the JS file to disk </code></pre></div> But again, it’s easy to add steps in between. Next, let’s take care of the fact that Angular apps often produce html that is not valid html5. We can automatically add <code>data-</code> prefixes to our various angular directive attributes by using the htmlify module: <div class="highlight"><pre class="highlight javascript"><code>var htmlify = require('gulp-angular-htmlify'); // ... .pipe(templateCache()) .pipe(htmlify()) // Add data- prefixes to non-html5-valid attributes .pipe(gulp.dest("dist")) </code></pre></div> As you can see, it’s fairly trivial to make changes to what started as an extremely basic gulp script. I wrote a couple angular starter templates that use gulp for compilation. One is meant for full web apps while the other is meant for creating angular libraries. <ul> <li><a href="https://github.com/adamalbrecht/angular-starter-kit">angular-starter-kit</a> - Build thick-client web apps. Be aware, this is pretty opinionated and won’t be for everyone.</li> <li><a href="https://github.com/adamalbrecht/angular-lib-template">angular-lib-template</a> - Build angular libraries</li> </ul> <hr> <h3 id="more-resources">More Resources</h3> <h3 id="documentation">Documentation:</h3> <ul> <li><a href="https://github.com/gulpjs/gulp/blob/master/docs/README.md">Gulp.js Documentation</a></li> </ul> <h3 id="common-gulp-utilities">Common Gulp Utilities:</h3> <ul> <li><a href="https://github.com/wearefractal/gulp-concat">gulp-concat</a> - Concatenate files</li> <li><a href="https://github.com/gulpjs/gulp-util">gulp-util</a> - Various gulp utility functions</li> <li><a href="https://github.com/peter-vilja/gulp-clean">gulp-clean</a> - Clean out a folder before writing to disk</li> <li><a href="https://github.com/nfroidure/StreamQueue">StreamQueue</a> - Combine multiple streams into one while preserving the order</li> <li><a href="https://github.com/robrich/gulp-if">gulp-if</a> - Apply actions to files that meet certain conditions</li> <li><a href="https://github.com/hparra/gulp-rename">gulp-rename</a> - Rename files</li> <li><a href="https://github.com/mikaelbr/gulp-notify">gulp-notify</a> - Show native OS notifications on compilation, errors, etc</li> <li><a href="https://github.com/avevlad/gulp-connect">gulp-connect</a> - Mini web server for running your app</li> </ul> <h3 id="common-gulp-pre-processors">Common Gulp Pre-Processors</h3> <ul> <li><a href="https://github.com/wearefractal/gulp-coffee">gulp-coffee</a> - Compile coffeescript</li> <li><a href="https://github.com/sindresorhus/gulp-ruby-sass">gulp-ruby-sass</a> - Compile (the ruby version of) sass and scss</li> <li><a href="https://github.com/plus3network/gulp-less">gulp-less</a> - Compile less.css</li> <li><a href="https://github.com/phated/gulp-jade">gulp-jade</a> - Compile jade templates</li> <li><a href="https://github.com/sindresorhus/gulp-markdown">gulp-markdown</a> - Compile markdown</li> </ul> <h3 id="minification-plugins">Minification Plugins</h3> <ul> <li><a href="https://github.com/terinjokes/gulp-uglify">gulp-uglify</a> - Minify / uglify code</li> <li><a href="https://github.com/jonathanepollack/gulp-minify-html">gulp-minify-html</a> - Minify html</li> <li><a href="https://www.npmjs.org/package/gulp-minify-css">gulp-minify-css</a> - Minify CSS</li> <li><a href="https://github.com/sindresorhus/gulp-imagemin">gulp-imagemin</a> - Compress images without losing quality</li> </ul> <h3 id="angular-helper-plugins">Angular Helper Plugins</h3> <ul> <li><a href="https://github.com/btford/ngmin">gulp-ngmin</a> - Make angular code friendly to minification</li> <li><a href="https://github.com/pgilad/gulp-angular-htmlify">gulp-angular-htmlify</a> - Make angular code valid html5</li> </ul>

#angularjs #gulpjs #javascript