closure-util

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.

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, [jvm], callback)

The compile function drives the Closure Compiler.

• options - 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}).
• 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 (an archive for revision of the library can be downloaded by looking for the "Download zip" link in the source browser).
• log_level - Logging level. Allowed values are silly, verbose, info, warn, and error (default is info).

Environment variables are given precedence over closure-util.json values. For example, the following would set the logging level for the install regardless of the default or anything found in closure-util.json:

closure_log_level=verbose npm install

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).