plovr: a Closure build tool

Currently, documentation on plovr is spread across several sources:

Appendix C of Closure: The Definitive Guide.
The demo on plovr.com.
The wiki for plovr on code.google.com.

Ultimately, information from the various online sources will be consolidated. Until then, this page contains a summary of how to use the most important features of plovr.

Using plovr During Development

The general idea behind plovr is that all of the configuration for your Closure build should be stored in a single file of JSON. (Ultimately, config files will be able to inherit from other config files, but that feature does not exist today.) The following is an example of a minimal (but functional) plovr config file:

// File: config.js
{
  "id": "sample",
  "paths": ".",
  "inputs": "main.js"
}

An example of a more complex config file (that leverages the modules feature of the Compiler) can be seen in the plovr repository. A config file declares which files should be compiled, where its dependencies can be found, and which compilation options should be used. (Many of these settings have appropriate default values and need not be specified.)

When plovr is started in server mode, it takes the path to one or more config files as input:

java -jar plovr.jar serve config.js

Once the plovr web server is started, it should not need to be restarted unless one of the config files is edited. (Some settings can be changed via query parameters, avoiding the need to restart plovr.) The primary way to access the output of plovr is by making a GET request. By default, plovr runs on port 9810, so loading the following URL in a browser will return the compiled code for the configuration with the specified id:

http://localhost:9810/compile?id=sample

This means that when developing your web application, you will need a <script> tag whose src attribute refers to the plovr URL that is shown above. This means that you will need to add logic to your web server to load JavaScript from plovr in development mode, but to load JavaScript from wherever your other static content is hosted in production mode. Hopefully your build system already has conditional logic for development and production modes that you can leverage in integrating plovr to your development process.

Once plovr is up and running, it will discover new JavaScript and Soy files that are added under directories specified by paths in the config file. For this reason, it is often easiest to declare a single file for inputs, such as main.js, and add or remove goog.require() and goog.provide() statements as appropriate to transitively include the desired libraries. This avoids the need to restart plovr and makes the insertion point for your application unambiguous.

Using plovr For Production

As explained in the overview, plovr is designed to produce a static JavaScript file that can be served in production. Running plovr as follows will print the compiled JavaScript to standard out, so it can be redirected to a file using ordinary shell commands:

java -jar plovr.jar build config.js > sample-compiled.js

It is up to you to upload sample-compiled.js to your static content server and to make sure that in production, the src attribute of your <script> tag points to sample-compiled.js.

(It is quite possible that future work for plovr will include better integration with popular web frameworks, such as Django, that will facilitate this process.)

More on Config Files

Config options are enumerated in the Java source code in ConfigOption.java. As plovr is evaluated by Closure developers, the names and JSON data types for these options may change, so until the API is frozen, the source code is the source of truth for what is expected.

The primary options of interest are likely the compilation mode and the warning level. The names of these properties in the plovr config are mode and level, respectively. The possible string values for mode are:

RAW Loads each input via its own <script> tag: does NOT run the Compiler, so no checks are performed.
WHITESPACE Loads all of the JavaScript code concatenated together with all whitespace and comments removed.
SIMPLE Loads the JavaScript as compiled with SIMPLE_OPTIMIZATIONS enabled.
ADVANCED Loads the JavaScript as compiled with ADVANCED_OPTIMIZATIONS enabled.

The possible string values for level are QUIET, DEFAULT, and VERBOSE, which correspond exactly to the warning levels supported by the Closure Compiler. Therefore, to change config.js to use the most aggressive compilation settings, set mode and level as follows:

{
  "id": "sample",
  "paths": ".",
  "inputs": "main.js",
  "mode": "ADVANCED",
  "level": "VERBOSE"
}

It is also possible to set the level for various types of Compiler checks with the checks property. Many of these checks are explained on the Closure Compiler wiki, though the DIAGNOSTIC_GROUP_NAMES variable in DiagnosticGroups.java is the real source of truth:

{
  "id": "sample",
  "paths": ".",
  "inputs": "main.js",
  "mode": "ADVANCED",
  "level": "VERBOSE",
  "checks": {
    // acceptable values are "ERROR", "WARNING", and "OFF" 
    "deprecated": "ERROR",
    "checkTypes": "ERROR",
    "nonStandardJsDocs": "WARNING"
  }
}

(Strictly speaking, JSON does not support comments in either the // or /* */ form, but such comments are allowed in plovr config files.)

Remember, the names and values of the config file have not been finalized, so it may be necessary to monitor the plovr source code as new versions are released.

Using plovr With Compiler Modules

Currently, the best way to learn how to use the modules feature of plovr is to examine the modules example in the plovr codebase. It is based off of the example in the "Partitioning Compiled Code into Modules" section in Chapter 12 of Closure: The Definitive Guide.

One important thing to note when using modules is that you will probably have to add code like the following to configure the goog.module.ModuleManager:

var moduleManager = goog.module.ModuleManager.getInstance();
moduleLoader.setDebugMode(true);
moduleManager.setAllModuleInfo(goog.global['PLOVR_MODULE_INFO']);
moduleManager.setModuleUris(goog.global['PLOVR_MODULE_URIS']);

When plovr generates the JavaScript for the modules, it includes some module data in global variables that are used for initialization, as shown above.

Special URLs

In addition to the /compile URL introduced in the first section, there are other URLs that plovr serves to provide additional information. Some of these are listed on the plovr wiki page on Google Code, though the best way to get the complete list is by exploring the plovr source code. There is also more information on these features of plovr in Appendix C of Closure: The Definitive Guide.