closure-util
v1.26.0Closure 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 matchinggoog.require
's that cannot be satisfied instead of throwing an exception. Optional. - config.closure -
boolean|undefined
Whether to include Closure library. Defaulttrue
.
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 isprocess.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 isprocess.cwd()
. All relative paths in the compiler options must be relative tocwd
. - 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
).