Javascript Package Management – NPM – Bower – Grunt
When I was writing my previous post about Java EE and Angular, I was overwhelmed with all the javascript files that I needed to include in my application to implement the behaviour that I was looking for. OK, not that many scripts actually, four in total: Angular JS (Angular also requires jQuery), ng-grid and UI Bootstrap. Unfortunately, it was not so simple. Each script, may also need a CSS file and some of the scripts depended on different versions from each others. Finally, I also needed to include all the files in my index.html. For that particular post, I ended up doing everything manually and it was a real pain. There must be a better way!
The Problem
In Java, whether you like it or not, Maven is the number one tool to perform this kind of management, but what about Javascript? I’m far from an expert, so after asking our friend Google about it, I was a bit surprised with the amount of existent tools to do the job and for a newcomer this seemed complicated and lacking a common solution generally accepted by the community. Here are a couple of interesting posts about the problem:
Which solution?
I was not exactly sure which tool should I use, so after a few talks with a couple of colleagues that were working in Javascript applications they recommended NPM-Bower-Grunt combo:
- NPM
- Bower
- Grunt
NPM stands for Node Package Manager. Sounds weird, since we are not developing a Node.js application here, but we need NPM to use Bower and Grunt.
Bower is a package manager for the web. It will manage all your web files: javascript, css and images.
Grunt is a task-based command line build tool for JavaScript projects.
Both Bower and Grunt are Node.js packaged modules and we only need NPM to download them. Bower is going to be responsible to download and manage all the javascript dependencies for our web application. Finally, Grunt will automate the task for adding the correct tags to the html files. Actually, Grunt also have tasks to concatenate and minify multiple files in a single one. This is useful to improve the performance of your application in production environments, but it was not may main focus.
The Setup
Paulo Grácio, a very good friend of mine that I work with, was kind enough to pick up my Java EE Angular sample on Github and setup everything needed to provide the application with Javascript Package Management. Thank you so much Paulo!
Maybe it’s a stupid comparison, but I’ll try to establish parallels with Java Maven build, to help people like me that are used to Maven to better understand what’s going on.
Install NPM
The pre-built installer of Node.js is all you need to have NPM up and running on your machine, but I actually followed this post to install NPM using Homebrew on OS X.
Now we need a package.json file in the root project folder. We are using this one:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | { "name": "javaee7-angular", "version": "1.0.0", "authors": [ "Roberto Cortez <radcortez@yahoo.com>", "Paulo Grácio <paulo.gracio@gmail.com>" ], "description": "javaee7-angular dependencies for Grunt.", "private": true, "devDependencies": { "load-grunt-tasks": "~0.6.0", "time-grunt": "~0.4.0", "grunt-contrib-clean": "~0.5.0", "grunt-wiredep": "~1.8.0", "grunt-contrib-htmlmin": "~0.3.0", "grunt-usemin": "~2.3.0", "grunt-contrib-copy": "~0.5.0", "grunt-contrib-concat": "~0.4.0", "grunt-contrib-uglify": "~0.5.0", "grunt-contrib-cssmin": "~0.9.0", "grunt-bower-install-simple": "~0.9.3" }, "engines": { "node": ">=0.8.0" } } |
In this file, you can find the node settings for your project. The most interesting stuff here is the devDependencies definition. Here you can find the Grunt task to download the project dependencies (grunt-bower-install-simple) and the task to inject the scripts and css in the index.html (grunt-wiredep). This is similar to the plugins definitions in a Maven pom.xml file. Running npm install should download everything you need to start using Grunt and the project tasks.
Managing Web Packages with Bower
Now we need to tell Bower which packages we want to include in the project. Add a file named bower.json in the root project folder:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | { "name": "javaee7-angular", "version": "1.0.0", "authors": [ "Roberto Cortez", "Paulo Grácio" ], "description": "javaee7-angular JavaScript dependencies.", "private": true, "dependencies": { "angular": "1.2.0", "jquery": "1.9.1", "angular-bootstrap": "0.10.0", "angular-grid": "2.0.7" } } |
Remember the original problem? Manage Angular, jQuery, ng-grid and UI Bootstrap dependencies? Here we have the definitions. I can compare it again like being a bit similar to the dependencies section in a Maven pom file for a Java project. Just a small detail, Bower uses Convention-over-Configuration to define project paths. This is important because the default location to download the javascript packages does not follow the Maven folder layout, so we should change Bower path to match Maven web app layout. To fix this, we need to add a file named .bowerrc to the project root folder:
1 2 3 | { "directory": "src/main/webapp/lib/bower" } |
Defining Grunt Tasks
To glue everything together, we use Grunt to run the different tasks, but first we need to add another file to the project root folder, Gruntfile.js:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 | 'use strict'; module.exports = function (grunt) { // Load grunt tasks automatically require('load-grunt-tasks')(grunt); /* * Time how long grunt tasks take to run, this might be important when having complex builds that take forever. * For now just to show how fancy grunt is. */ require('time-grunt')(grunt); // init required configurations for each task. grunt.initConfig({ // Project settings config: { path: { webapp: { root: 'src/main/webapp' }, temp: { root: 'temp' }, build: { root: 'build' } } }, // From grunt-contrib-clean clean: { build: [ '<%= config.path.temp.root %>', '<%= config.path.build.root %>' ] }, // From grunt-bower-install-simple. Downloads the web dependencies. "bower-install-simple": { options: { color: true, production: false } }, // From grunt-wiredep. Automatically inject Bower components into the HTML file wiredep: { target: { src: '<%= config.path.webapp.root %>/index.html', ignorePath: '<%= config.path.webapp.root %>' } }, // From grunt-contrib-copy. Copies remaining files to places other tasks can use copy: { build: { files: [ { src: '<%= config.path.webapp.root %>/index.html', dest: '<%= config.path.build.root %>/index.html' } ] } }, // From grunt-contrib-htmlmin. Minifies index.html file. htmlmin: { prod: { options: { collapseBooleanAttributes: true, collapseWhitespace: true, removeComments: true, removeCommentsFromCDATA: true, removeEmptyAttributes: true, removeOptionalTags: true, removeRedundantAttributes: true, useShortDoctype: true }, files: [ { expand: true, cwd: '<%= config.path.build.root %>', src: ['index.html'], dest: '<%= config.path.build.root %>' } ] } }, // From grunt-usemin. Reads HTML for usemin blocks to enable smart builds useminPrepare: { html: '<%= config.path.webapp.root %>/index.html', options: { staging: '<%= config.path.temp.root %>', root: '<%= config.path.webapp.root %>', dest: '<%= config.path.build.root %>' } }, // From grunt-usemin. usemin: { html: '<%= config.path.build.root %>/index.html' }, // From grunt-contrib-uglify. uglify: { options: { mangle: false } } } ); // Task: Build production version ready for deployment grunt.registerTask('build', [ 'clean:build', 'bower-install-simple', 'wiredep', 'useminPrepare', 'concat:generated', 'cssmin', 'uglify', 'copy:build', 'usemin', 'htmlmin' ]); grunt.registerTask('default', [ 'build' ]); }; |
For this file, we are just adding configurations to each Grunt task. We can also assemble all the tasks together to run in our own defined task named build or default. This is like defining our own Maven build lifecycle (which is not possible in Maven) and configuring the plugins settings. So, we actually have plugins (tasks) definitions in one file (package.json) and plugins (tasks) settings in a separate file (Gruntfile.js).
There is one more thing to do: we need to add a few special placeholders into our HTML files so that the Grunt tasks can add Javascript and CSS files automatically, based on Bower dependencies. For this project we have an unique index.html file and the head section should look like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | <head> <title>javaee7-angular</title> <link rel="stylesheet" href="http://netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css"> <!-- build:css css/third-party.css --> <!-- bower:css --> <!-- endbower --> <!-- endbuild --> <!-- build:css css/application.css --> <link rel="stylesheet" type="text/css" href="css/style.css"/> <!-- endbuild --> <!-- build:js lib/third-party.js --> <!-- bower:js --> <!-- endbower --> <!-- endbuild --> <!-- build:js script/all.js --> <script src="script/person.js"></script> <!-- endbuild --> </head> |
The <!-- bower:css --> marks the location in the html file where the css files dependencies must be inserted and <!-- build:css css/third-party.css --> is used to indicate the merged file with all the css code. For <!-- bower:js --> and <!-- build:js lib/third-party.js --> it works the some way. Note that we have separated the external files from the own application files.
Final Structure
The project structure result is the following:
Executing Grunt Tasks
After all this setup, we are finally ready to execute Grunt tasks and have our web files managed! So, going from the start, we execute from the command line in the project folder root:
npm install
followed by
npm install -g grunt-cli
finally
grunt
You will notice the following:
- A node_modules folder is created with all of the Bower and Grunt dependencies.
- A src/main/webapp/lib/bower folder is created with all of the web application dependencies (Angular, jQuery, ng-grid and UI Bootstrap).
- The src/main/webapp/index.html file is injected with the needed Javascript and CSS files.
- A build folder is generated with an optimised version of the web application (files concatenated and minified).
The end result:
You can also execute individual Grunt tasks:
grunt bower – Downloads the web application dependencies.
grunt bowerInstall – Modifies and inject the required files in your index.html.
Resources
You can find the updated Java EE 7 – Angular JS example with Javascript Package Management in Github, here. For the moment it’s in a branch but we intend to merge it with the original example.
Update
In the meanwhile I have merged this code with the original example. Please, download the original source of this post from the release 2.0. You can also clone the repo, and checkout the tag from release 2.0 with the following command: git checkout 2.0.
Final Thoughts
Uff! It was not easy to do this. A lot of files to add and to configure and a lot of tools to study. Maybe there is an easier way to accomplish the same using other existent setups and tools in the Javascript landscape. I cannot tell you this is the best, since I would have to setup all the other solutions around the Javascript landscape, but this is a possible approach and it works. Just a couple of weeks after working on this, I found the following:
And just like that Grunt and RequireJS are out, it’s all about Gulp and Browserify now
Don’t get me wrong, but I feel that the Javascript landscape is popping build tools like mushrooms. In my opinion it would be better to have a single standardised tool that everyone could use. Let’s see what is going to happen in the future.
Probably it could also be easier to use Yeoman to generate the structure, but we also wanted to learn more about the individuals tools, and I think you learn a bit more by doing things manually the first couple of times.
A Special Thanks
To Paulo Grácio for updating the Java EE 7 – Angular JS sample with all this setup! Thank you Paulo!