Bundling with browserify (for hslayers pre 1.0.0.) - hslayers/hslayers-ng GitHub Wiki

Prerequisites

To create a hslayers-ng application bundle we need to have some dev dependencies installed first.

npm i -S browserify deamdify exposify

They are also included in hslayers devdependencies so

npm install --only=dev

should work too.

If hslayers is cloned from the repository and not installed through npm, then npm installl inside hslayers-ng directory is needed.

Browserify

A Hslayers application usually consists of one app.js file, many hslayers files and none or a couple application specific javascript files. To make the startup times faster, all of javascript files can be bundled into one big bundle.js which can further be compressed. This is done with the help of Browserify. A node script which uses browserify js API is provided:

var browserify = require('browserify');
var fs = require('fs');
var common_paths = require('./node_modules/hslayers-ng/common_paths');
common_paths.paths.push(__dirname);
var b = browserify({
    paths: common_paths.paths
});
var bundleFs = fs.createWriteStream(__dirname + '/bundle.js')
b.add(__dirname + '/app.js');
b.transform('exposify', {
    global: true,
    expose: {jquery: '$'}
});
b.transform('deamdify', {global: true});
b.bundle().pipe(bundleFs);

This can be saved in build.js file and then called with node build.js

Inside the script one needs to specify the main startup script for the application - app.js in this case. Browserify then will traverse all its dependencies and bundle them. It will also expose some of the libraries as globals (angular for example).

Path to common_paths.js file needs to be provided for the application to know the directory of hslayers-ng. Inside this script we specify where the locations of hslayers components and dependencies are, because sometimes browserify would not be able to decide the correct filename to load ('geojson' dependency resides 'hs.source.GeoJSON' file, 'ol' library is in 'openlayers/dist/ol' and not 'ol/ol.js' etc.). It also decides if to load the dependencies from hslayers-ng/node_modules or from applications node_modules in the case when hslayers is installed through npm itself.

Two transformations will be applied to the libraries and hslayers-ng code: Exposify and Deamdify.

Deamdify tranforms hslayers-ng AMD modules into nodejs style modules, so the resulting bundle can be used without a separate loader such as RequireJS.

Exposify with the help of global: true option allows the bundle to use jQuery object from the container site because jQuery in most cases is already present in many CMSes and otherwise would be included twice - inside cms and also through browserifys bundling process, because Bootstrap, which is a dependency of hslayers-ng, also requires jQuery. Including jQuery twice would break Bootstraps modal dialog functionality.

Hslayers as a standalone directory

The above build script uses hslayers-ng installed through npm, but in some cases, when one needs to have more flexibility to change hslayers code, developing on a trunk or forked version or hslayers is preferred. In that case

var common_paths = require('./node_modules/hslayers-ng/common_paths');

needs to be substituted with

var common_paths = require('../hslayers-ng/common_paths');

or other path to hslayers-ng. In this example hslayers resides in a directory at the same level as the container application, thus must be accesible on the webserver to load the html templates. Its also possible to use a symlink to hslayers-ng and tin that case './hslayers-ng/common_paths' could be used.