Closure Builder - Closure build system
======================================

[![Build status](https://travis-ci.org/google/closure-builder.svg?branch=master)](http://travis-ci.org/google/closure-builder)
[![Code Climate](https://codeclimate.com/github/google/closure-builder/badges/gpa.svg)](https://codeclimate.com/github/google/closure-builder)
[![NPM version](https://img.shields.io/npm/v/closure-builder.svg)](https://www.npmjs.org/package/closure-builder)

Closure build system to easily compile Soy template files together with
Closure JavaScript files without the need to configure anything.
The Google Closure library will be included automatically if needed.

This simple build system could be also used for normal css, js, nodejs  and
static files as well.

* [Installation](#installation)
* [Basic Usage](#basic-usage)
* [Options](#options)
* [Function callback](#function-callback)
* [Example build configurations](#example-build-configurations)
  * [Compile closure JavaScript files](#compile-closure-javascript-files)
  * [Compile closure Javascript files with soy files](#compile-closure-javascript-files-with-soy-files)
  * [Compile soy files](#compile-soy-files)
  * [Compile JavaScript files](#compile-javascript-files)
  * [Compile Node.js files](#compile-node-js-files)
  * [Compile css files](#compile-css-files)
  * [Copy Resources](#copy-resources)
  * [Copy Remote Resources](#copy-remote-resources)
* [Best practise](#best-practise)
* [Development](#development)
* [Disclaimer](#disclaimer)
* [Author](#author)
* [License](#license)


Installation
------------
Use NPM using `npm install closure-builder` or fork, clone download the source
on GitHub to get the latest version.


Basic Usage
-----------

```javascript
var closureBuilder = require('closure-builder');
var glob = closureBuilder.globSupport();

closureBuilder.build({
  name: 'goog.namespace',
  srcs: glob([
    'src/**/*.js',
    'soy/**/*.soy'
  ]),
  deps: [...],
  out: 'genfiles/whatever.js'
});
```


Options
-------
All of the options will be defined inside the BUILD rule.
But there is not limit of BUILD rules which could be setup for your needs.

#### Required ####
These basic required options for compiling are:
- `name` Closure namespace to compiler or unique name of your build rule
- `srcs` List of (Soy, CSS, Closure or JavaScript files) which should be compiled
- `out` Output path / output file for the compiled Soy, Closure or JavaScript files

For copying files the required options are:
- `name` Unique name of your build rule
- `resources` Resource files which will be copied to the out folder
- `out` Output path / output file for the compiled Soy, Closure or JavaScript files


#### Additional ####
These options could be used for adding additional information:
- `deps` Dependencies like additional closure files or additional file for the compiler
- `license` Additional license header file which will be include as header to the compiled files
- `debug` If true display additional debug informations
- `trace` If true display additional trace informations
- `externs` Additional JavaScript externs for the compiler

#### Options ####
The following options are available for the closure and soy compiler:
- `options.soy` Additional settings for the Soy compiler
- `options.closure` Additional settings for the Closure compiler
- `options.exclude_test` If true *_test.* files will be excluded

#### Closure compiler warnings ####
To adjust the Closure compiler warnings, you could use
`options.closure.jscomp_...` or the shortcut `jscomp_...`.
- `jscomp_error`  List of compiler checks which produce an error message.
- `jscomp_warning` List of compiler checks which produce an warning message.
- `jscomp_off` List of compiler checks which should be disabled.

See full [list of compiler checks](https://github.com/google/closure-compiler/wiki/Warnings#warnings-categories)

```javascript
closureBuilder.build({
  name: 'Closure compiler warnings',
  options: {
    closure : {
      jscomp_error: ['deprecated', 'extraRequire',
      'missingProvide', 'missingRequire', 'newCheckTypes']
    }
  },
  ...
}
```

#### Not implemented yet ####
The following options are partially implemented and should not be used:
- `data`
- `compress`
- `type`


Function Callback
-----------------
For performance reasons the tasks will be executed asynchrone whenever it
is possible.

If you need to know exactly if an tasks has finished you could add a callback
as well.

```javascript
var closureBuilder = require('closure-builder');
var callbackExample = function(errors, warnings, files, results) {
  ...
};

closureBuilder.build({
  ...
}, callbackExample.bind(this));
```

The callback will be called with the following parameters:
- `errors` Errors if any
- `warnings` Warnings if any
- `files` Single output file or list of output files if any
- `results` Result if any


Example build configurations
----------------------------
These example shows the basic usage for the different file types.
You could define as many build rules you want.
Please keep in mind to add the needed require before like:
```javascript
var closureBuilder = require('closure-builder');
var glob = closureBuilder.globSupport();

closureBuilder.build({
  ...
});
```


#### Compile Closure JavaScript files ####
Compiling Closure JavaScript files for the given namespace to an single
JavaScript file.
```javascript
closureBuilder.build({
  name: 'goog.namespace',
  srcs: glob([
    'src/js/*.js'
  ]),
  out: 'genfiles/merged-and-minified.js'
});
```

#### Compile Closure JavaScript files with Soy files ####
Compiling Closure JavaScript files and associated Soy files to a single
javascript file.
```javascript
closureBuilder.build({
  name: 'goog.namespace',
  srcs: glob([
    'src/**/*.js',
    'soy/**/*.soy'
  ]),
  deps: [...],
  out: 'genfiles/compiled.js'
});
```

#### Compile Closure JavaScript files with externs ####
Compiling Closure JavaScript files with JavaScript externs.
javascript file.
```javascript
closureBuilder.build({
  name: 'goog.namespace',
  srcs: glob([
    'src/**/*.js',
  ]),
  externs: [
    'src/externs/global.js'
  ],
  out: 'genfiles/compiled.js'
});
```

#### Compile Soy files ####
Compiling Soy files into Soy JavaScript files to an targeted directory.
```javascript
closureBuilder.build({
  name: 'soy_files',
  srcs: glob([
    'soy/**/*.soy'
  ]),
  out: 'genfiles/compiled_soy_files/'
});
```

#### Compile JavaScript files ####
Combine several JavaScript files to a single JavaScript file.
```javascript
closureBuilder.build({
  name: 'javascript_files',
  srcs: glob([
    'src/js/*.js'
  ]),
  out: 'genfiles/merged-and-minified.js'
});
```

#### Compile Node.js files ####
Combine node.js JavaScript files with browserify to a single JavaScript bundle.
```javascript
closureBuilder.build({
  name: 'node_bundle_files',
  srcs: glob([
    'src/js/node_file.js'
  ]),
  out: 'genfiles/node_bundle.js'
});
```

#### Compile CSS files ####
Combine and minified several CSS files to a single CSS file.
```javascript
closureBuilder.build({
  name: 'css_files',
  srcs: glob([
    'src/css/*.css'
  ]),
  out: 'genfiles/merged-and-minified.css'
});
```

#### Copy resources ####
Copy static resources from the different location to the target directory.
```javascript
closureBuilder.build({
  name: 'static_resources',
  resources: glob([
    'static/css/*.css',
    'static/htm/*.htm',
    'static/html/*.html',
    'static/jpg/*.jpg',
    'static/gif/*.gif',
    'static/png/*.png',
    'static/xml/*.xml'
  ]),
  out: 'genfiles/static-folder/'
});
```


#### Copy remote resources ####
Copy resources from an remote location to the target directory.
```javascript
closureBuilder.build({
  name: 'static_resources',
  resources: [
    'https://raw.githubusercontent.com/google/closure-builder/master/test_files/resources/file.js',
    'https://raw.githubusercontent.com/google/closure-builder/master/test_files/resources/file.html',
    'https://raw.githubusercontent.com/google/closure-builder/master/test_files/resources/file.jpg',
    'https://raw.githubusercontent.com/google/closure-builder/master/test_files/resources/file.gif',
    'https://raw.githubusercontent.com/google/closure-builder/master/test_files/resources/file.png',
    'https://raw.githubusercontent.com/google/closure-builder/master/test_files/resources/file.xml',
    'https://raw.githubusercontent.com/google/closure-builder/master/test_files/resources/file.css'
  ],
  out: 'genfiles/static-folder/'
});
```


#### Convert Markdown (.md) to .html file ####
Convert markdown (.md) to .html file.
```javascript
closureBuilder.build({
  name: 'md_file',
  markdown: [
    'README.md'
  ],
  out: 'genfiles/'
});
```


Best practise
-------------
For an better overview, you could split your build rules to several files.
They could be placed in an "build" folder or something like this.
Example: https://github.com/google/coding-with-chrome/tree/master/build

This allows you to rebuild only some of the files if needed.

Example package.json:
```
 "scripts": {
    "build": "npm run build-static-files && npm run build-remote-files && npm run build-extra-files && npm run build-cwc-files",
    "rebuild": "npm run build-static-files && npm run build-cwc-files",
    "build-static-files": "node build/static_files.js",
    "build-remote-files": "node build/remote_files.js",
    "build-extra-files": "node build/extra_files.js",
    "build-cwc-files": "node build/cwc_files.js",
 }
```


Development
-----------
There are some automated scripts which will help you for development on the
closure-builder project.

### Updating dependencies ###
Before you start working, run `npm run update` to update the dependencies to
the latest package versions.

### Code Style ###
Run `npm run lint` to make sure that your code is according the general style.

### Testing ###
Tests could be performed with `npm run test`. Before the test runs it will
automatically run the linter to make sure that the code has no syntax errors.

### Deploying ###
Add all your files and create your commit, but instead of using "git push"
directly please use `npm run deploy` instead.
It will automatically run some tests and increase the versions number by 0.0.1.


Disclaimer
----------
This is not an official Google product.


Author
------
[Markus Bordihn](https://github.com/MarkusBordihn)


License
-------
Apache License, Version 2.0 - http://www.apache.org/licenses/LICENSE-2.0.htm
