Creating a custom build of OpenLayers 3


The OpenLayers 3 Beta 2 release provides a lot of integrated functionality out of the box. Since the library likely includes more than needed for any single application, it is important to know how to generate custom builds with just the relevant code. We’re currently working on making this process a whole lot simpler and easier, including developing a web-based build tool. In the meantime, this post describes how to generate a custom build.

No Irrelevant Code

OpenLayers 3 uses the Google Closure Compiler (in advanced mode) to create a custom build containing only the parts of the library needed for an application. To produce a minified version containing only the required parts of the API, the compiler removes all the irrelevant code. OpenLayers 3 currently uses Plovr to drive the Closure Compiler, though we anticipate this will change as the build process improves.

This post assumes that OpenLayers 3 is configured locally with a working build environment; if not, please check out the Developer Guide to setup a development environment. With that in mind, generating a custom build requires the creation of two files:

  1. a build configuration file (called my-config.json below)
  2. an exports file file (called my-exports.js below)

Build Configuration File

The build configuration file sets some build flags and instructs Plovr which other files to use (see the Plovr documentation for more detail). In the buildcfg directory, create your my-config.json build configuration file. Use the content below as a starting point.

  "define": {
    "ol.ENABLE_DOM": false,
    "ol.ENABLE_WEBGL": false,
    "ol.ENABLE_PROJ4JS" : false,
    "ol.ENABLE_VECTOR": false,
    "goog.dom.ASSUME_STANDARDS_MODE": true,
    "goog.DEBUG": false
  "inherits": "base.json",
  "inputs": ["my-exports.js"],
  "externs": [
  "paths": [

The define section of the build configuration file disables the DOM and the WebGL renderers,  specifying that we only need the Canvas renderer. In addition, support for vector data and Proj4JS is disabled, resulting in a smaller build size.

Exports File

The next file you need to create will contain export statements that essentially tell the compiler what methods and properties you’ll be using in your application. Create a file named my-exports.js in the buildcfg directory. You can start by adding the content in this complete exports file from GeoServer’s preview page.

Assuming you are using a MousePosition control in our application, a subset of your exports file would look like this:



To build the compiled version of the library tailored to your application, run the following

./ build/src/external/externs/types.js
java -jar build/plovr-81ed862.jar build buildcfg/my-config.json > ol.min.js

The end result will be saved in ol.min.js. Given the exports for the GeoServer preview page, the resulting file is about 37 kB after GZIP compression.

Interested in using OpenLayers in your enterprise? Boundless provides support, training, and maintenance. Contact us to learn more.


Leave a Reply

Your email address will not be published.

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=""> <strike> <strong>