closure-util

Utilities for Closure Library based projects.

Closure Util

Utilities for working with Closure Library projects.

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

The closure-util command line utility allows you to update (or install) specific versions of the Closure Compiler or Closure Library for use with your project. 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 commands below.

  • 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 --help - Display command usage and options.

Setup:

npm install

Run tests:

npm test

Run tests continuously during development:

npm start

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