azavea/nyc-trees — pull request #21 by maurizi (2014-10-17 20:32:10+00:00)
Title: Draft of client-side tooling

The main tool used is [gulp](http://gulpjs.com/), which is exposed through `npm run` to avoid version conflicts.

JS is compiled using browserify and minified using uglify, using sourcemaps in a separate file for the entire process so minifed JS bundles show sourcemaps for the original files, with one bundle per entry file (it is assumed each entry bundle will correspond to a page and/or feature).

A browserify plugin, [factor-bundle](https://github.com/substack/factor-bundle) is used to automatically pull common dependencies between each bundle into a separate bundle.

[gulp-rev-all](https://github.com/smysnk/gulp-rev-all) is used to add a version to each file based on it's md5 hash. `gulp-rev-all` will modify CSS file so links to images point to the hashed version. A file called `rev-manifest.json` is created as part of this task which contains mappings of original filename -> versioned filename, which we can use from Django when including that file on the page.

- To create JS bundles, compile sass, and concatenate third-party css, minify CSS and JS, and version files using `gulp-rev-all`, use `gulp` or `npm run build`.
- To do the above but skip minification and versioning, use `gulp build --debug` or `npm run build-debug`.
- To watch files and automatically rebuild the JS or sass files when they change, use `gulp watch --debug` or `npm run watch`. This will also start a livereload server.

`gulp build` and `gulp watch` without the `--debug` flag are intentionally not exposed through `npm run`.

**Note** The `watch` and `build` tasks do not do versioning of files, and thus files will end up in a different in the `assets/` directory, not the `static/` directory. This is intentional.