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 than 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 existing 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 chats with of colleagues who were working in JavaScript applications, I was steered towards an NPM-Bower-Grunt combo:

NPM stands for Node Package Manager. Sounds weird as we’re 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 has 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 my main focus.

Setting up

Paulo Grácio, a very good friend and colleague of mine, was kind enough to pick up my Java EE Angular sample on GitHub and set up 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:

{
    "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:

{
    "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 by noting that it’s 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 the Bower path to match the Maven web app layout. To fix this, we need to add a file named .bowerrc to the project root folder:

{
    "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:

'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’re 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 headsection should look like this:

<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 was set up, 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 existing kits and tools in the JavaScript landscape. I cannot tell you this is the best, since I would have to set up 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 happens 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 set up! Thank you Paulo!

JavaScript Package Management with NPM, Bower and Grunt

About The Author
- Freelancer. Passionate Java Developer.

2 Comments

  • Dimitri Hautot
    Reply

    Hi Roberto,

    I’m not versed that much into HTML/CSS/JS technologies; I am a Java developer too.
    But I had to dig into it recently. Thanks for the article, I learned a lot of useful Grunt plugins, that’s nice.

    Did you know that to manage the Javascript dependencies, you could also use Maven? Have a look at the http://www.webjars.org/ website, and have fun!

    • Roberto Cortez
      Reply

      Hi Dimitri,

      Thank you for your comment. I’ve actually only learned about webjars after writing the article, but I haven’t tried them yet. It’s on my long TODO list. Thank you for pointing that out. I was planning to also write something with webjars.

      Cheers,
      Roberto

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>