boilerplate-gulp

Boilerplate gulp tasks for client side packages

Client-side JavaScript Module Builder

All the things you would want in a build system for client-side JavaScript projects in one package.

(Building angular modules? Then you'll find this more useful: boilerplate-gulp-angular)

Capabilities

  • Compiles JavaScript CommonJS modules into a single file (browserify) which can be loaded directly in a browser, via CommonJS loader, or a AMD loader. Produces both an unminified version and a minified version with source maps.
  • Compiles LESS files into a single CSS file. Produces both an unminified version and a minified version with a source maps.
  • Run cross-browser unit tests (jasmine & karma) using Chrome, Firefox, and Safari.
  • Generates coverage reports (istanbul) for unit tests.
  • Lints CSS (recess) and JS (jshint)
  • Generate complexity/maintainability reports (plato)
  • Launch a development server (connect) which automatically reloads browsers (livereload) as files get rebuild incrementally (gulp)
  • Automatically formats JavaScript files to match a given style guide (js beautifier).

Technology Used

  • gulp - Build engine
  • browserify - Bundles CommonJS modules for use in browsers
  • jshint - JavaScript linter
  • uglify - JavaScript minifier
  • less - CSS preprocessor
  • csso - CSS minifier
  • recess - CSS linter
  • jasmine - JavaScript testing framework
  • karma - Cross-browser unit test runner
  • istanbul - JavaScript test coverage analysis tool
  • js beautifier - JavaScript reformatter
  • plato - Complexity and maintainability analysis for JavaScript source code
  • connect - HTTP server for development use
  • livereload - Automatic reloading of browsers which are connected to the development server

To see it in action see client-side-seed.

Tasks

# Creates a clean, full build with testing, linting, reporting and 
# minification then copies the results to the ./dist folder. 
gulp
 
# Incrementally builds files as they're modified and then 
# executes testing and linting tasks. Also starts a server on port 3000 
# which serves both the example and build directories. Connected browsers 
# will automatically refresh when files are updated. 
gulp dev
 
# Runs unit tests and generates coverage reports to ./report 
gulp test
 
# Runs gulp test along with generating code complexity reports ./report 
gulp reports
 
# Rewrite JavaScript source files by passing them through JS Beautifier 
gulp fix-style
 

Use

If you don't have a package.json file at the root of your code repository, execute npm init to generate one. Modify the "main" key in package.json to point to your root CommonJS module, whatever is assigned to module.exports or exports in this module will be "exported" to the window.<package.name> variable on browsers.

Next, executing npm install --save-dev gulp boilerplate-gulp. Then modify your gulpfile.js (or create one):

var gulp = require('gulp'), 
  boilerplate = require('boilerplate-gulp');
 
boilerplate(gulp, {
  jsMain: 'path/to/js/main.js',
  cssMain: 'path/to/css/main.less'
});
 
// Rest of your gulp file, potentially overwriting the boilerplate-gulp tasks... 

Default Directory Structure

  • dist/ - The distributable files for this package, updated when gulp is run
  • build/ - The build directory used by gulp during builds.
  • example/ - The root directory served during gulp dev.
  • src/ - Source code and accompanying unit tests
  • test/ - End-to-end tests
  • reports/ - Generated reports (testing, coverage, complexity)