Closure Util

Utilities for working with Closure Library projects.

API

new Manager(config)

A script manager parses scripts for dependencies and watches those scripts for changes, updating dependencies as scripts are added, modified, or deleted. A manager is used in conjunction with a server for providing a debug loader during development.

Main options:

• config.lib - string|Array.<string> A list of path patterns for your library scripts (e.g. 'lib/**/*.js'). Note that path delimiters in these patterns should always be forward slashes (even on Windows).
• config.main - string|Array.<string> Patterns for your main script(s).

More advanced options:

• config.ignoreRequires - string|undefined A regular expression string. The manager will ignore matching goog.require's that cannot be satisfied instead of throwing an exception. Optional.
• config.closure - boolean|undefined Whether to include Closure library. Default true.

The manager is an event emitter that emits the following events:

• ready - The manager is ready (all scripts parsed and dependencies resolved).
• error - Listeners will be called with an Error instance representing what went wrong.

new Server(config)

Create a development server providing a script loader and static assets.

• config.manager - Manager A script manager.
• config.root - string Path to root directory for scripts and static assets (default is process.cwd()).
• config.loader - string URL path for script loader.

var closure = require('closure-util');

var manager = new closure.Manager({
  lib: ['path/to/app/src/**/*.js'],
  main: 'path/to/app/examples/*.js'
});
manager.on('error', function(e) { throw e; });
manager.on('ready', function() {
  var server = new closure.Server({
    manager: manager,
    root: 'path/to/app', // static resources will be served from here
    loader: '/examples/lib.js' // the script loader will be provided here
    // this assumes the main script can be derived from the query string like:
    // <script src='lib.js?main=example-1.js'></script>
    // this can be customized by providing a getMain method that accepts a
    // request object and returns the path to the main script
  });
  server.listen(3000);
});

getDependencies(config, callback)

The getDependencies function generates a list of script paths in dependency order.

• config - Object A configuration object of the same form as the manager config.
• callback - function(Error, Array.<string>) Called with a list of script paths in dependency order (or a parsing error).

compile(options, callback)

The compile function drives the Closure Compiler.

• options.compile - Object Options for the compiler (without the -- prefix). E.g. the --output_wrapper option could be specified with {output_wrapper: '(function(){%output%})();'}. For options that can be specified multiple times, provide an array of values (e.g. {js: ['one.js', 'two.js']}). For options that are flags (no value), provide a boolean (e.g. {use_types_for_optimization: true}).
• options.cwd - string Optional path to set as the current working directory. Default is process.cwd(). All relative paths in the compiler options must be relative to cwd.
• options.jvm - Array.<string> Optional arguments for the JVM. If this argument is absent (if the function is called with two arguments), ['-server', '-XX:+TieredCompilation'] will be used as JVM arguments. To use different arguments, provide an array.
• callback - function(Error, string) Called with the compiler output (or any compilation error).

Configuration

The closure-util package downloads the Closure Compiler and Closure Library when installed. To use a different version of these resources, you can provide some basic configuration options before running npm install. Your configuration options can come from a number of different sources. The most straightforward way is to include a closure-util.json file in your project. You can also provide configuration options via environment variables. Environment variables have the closure_ prefix in front of the options described below (e.g. closure_log_level to specify the log_level option).

Available configuration options (see default-config.json for default values):

• compiler_url - URL for the compiler zip archive (e.g. http://dl.google.com/closure-compiler/compiler-latest.zip).
• library_url - URL for the Closure Library zip archive (e.g. https://github.com/google/closure-library/archive/master.zip).

CLI

The closure-util command line utility provides update commands for updating (or installing) specific versions of the Closure Compiler and Closure Library for use with your project, a build command for building your project using the Closure Compiler, and a serve command for starting a development server for your project.

• closure-util update - Update both the Compiler and Library.
• closure-util update-compiler - Update the Compiler.
• closure-util update-library - Update the Library.
• closure-util build - Build a JavaScript application.
• closure-util serve - Start a development server.
• closure-util --help - Display command usage and options.

See the configuration section above for information on how to configure URLs for specific versions of the Compiler or Library. The closure-util utility will look for this configuration when executing one of the update, update-compiler or update-library commands.

This is how the build command is used:

closure-util build config.json app.min.js

where config.json is a build config file and app.min.js in the output file including the compiled code. As an example for a build config file see the config.json file used in the closure-util tests. The config file should include a "lib" and a "compile" sections.

This is how the serve command is used:

closure-util serve config.json

where config.json is a config file. You can look at the config.json again. For the serve command the config file should include a "lib" and a "serve" sections.

Development

Setup:

npm install

Run tests:

npm test

Run tests continuously during development:

npm start

Publishing

To publish a new version of the closure-util package, first create a tag, and then publish. Creating a tag can be done with the npm version command. This is a handy way to update package.json and create a git tag named like the new version. The npm publish command is used to publish the package to the registry.

Example of publishing a new minor version (to increment the major version or create a patch release, replace minor with major or patch). This assumes you have the latest from master and your remote is named openlayers.

npm version minor
git push --tags openlayers master && npm publish

To publish a new version, you need to have signed up for an account with the registry. After signing up for an account, contact one of the current closure-util maintainers and ask to be added (with npm owner).