Building

Boomerang is split into the main framework (boomerang.js) and plugins (plugins/*.js).

boomerang.js on its own will not do anything interesting. To enable performance measurements of your site, you will want to include several plugins.

Choosing Plugins

Each plugin lives on its own in the plugins/ directory. Plugins are split into core measurement components, though some depend on each other.

The default set of plugins for a "full" build of Boomerang can be seen in plugins.json in the root directory. You can modify this file to choose which plugins you want for measurement.

You can read about each plugin in its documentation. Here is a basic description of each plugin:

There are also a few utility plugins:

To monitor basic page load performance for a traditional website, we would recommend:

To monitor a Single Page App website, we would additionally recommend:

Including Boomerang on your site.

boomerang can be included on your page in one of two ways: synchronously or asynchronously.

The asynchronous method is recommended.

After the core JavaScript files are loaded, you will need to call BOOMR.init to initialize Boomerang and all of its plugins. See each plugin's documentation for the available configuration options.

The simple synchronous way

Simply include boomerang.js and any desired plugins as a <script> tag.

<script src="boomerang.js"></script>
<script src="plugins/rt.js"></script>
<!-- any other plugins you want to include -->
<script>
  BOOMR.init({
    beacon_url: "http://yoursite.com/beacon/"
  });
</script>

Each plugin has its own configuration as well -- these configuration options should be included in the BOOMR.init() call:

BOOMR.init({
  beacon_url: "http://yoursite.com/beacon/",
  ResourceTiming: {
    enabled: true,
    clearOnBeacon: true
  }
});

The faster, more involved, asynchronous way

Loading boomerang asynchronously ensures that even if boomerang.js is unavailable (or loads slowly), your host page will not be affected.

1. Add a plugin to init your code

Create a plugin (or use the sample zzz-last-plugin.js) with a call to BOOMR.init:

BOOMR.init({
  config: parameters,
  ...
});
BOOMR.t_end = new Date().getTime();

You could also include any other code you need. For example, you could include a timer to measure when boomerang has finished loading (as above).

2. Build boomerang

The build process bundles boomerang.js and all of the plugins listed in plugins.json (in that order).

To build boomerang with all of your desired plugins, you would run:

grunt clean build

This creates a deployable boomerang in the build directory, e.g. build/boomerang-<version>.min.js.

Install this file on your web server or origin server where your CDN can pick it up. Set a far future max-age header for it. This file will never change.

The Build Process

Build requires NodeJS to execute Grunt.js to build Boomerang.

To install Grunt globally:

npm install -g grunt-cli

You can get a full build of boomerang by running the following:

grunt clean build

The main build targets are:

  • clean cleans the build/ directory
  • build builds a new version of Boomerang from scratch
  • lint runs lint on the project
  • test runs tests

A full list of build targets are avaialble in Gruntfile.js.

Grunt build options:

  • --build-number Specifies the minor build number
  • --build-revision Specifies the revision build number

Build Numbers

Boomerang follows SemVer:

major.minor.revision

For each build of Boomerang, the major build version is specified in package.json as releaseVersion.

The minor version defaults to 0. Each build can then specify its --build-number to change the minor version.

The revision defaults to 0. Each build can then specify its --build-revision to change the revision.