Angular.js Builder

All the things you would want in a build system for AngularJS projects in one package.

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. Files run through ng-annotate prior to minification.
• Compiles SASS 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.
• Run cross-browser e2e tests (jasmine & protractor) using Chrome and Firefox.
• 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
• protractor - Cross-browser end-to-end test runner
• ng-annotate - Annotates angular files for minification without messing up dependency injection due to variable name rewriting
• browserify - Bundles CommonJS modules for use in browsers
• jshint - JavaScript linter
• uglify - JavaScript minifier
• sass - 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 and e2e 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-angular. Then modify your gulpfile.js (or create one):

var gulp = require('gulp'), 
  angularBuilder = require('boilerplate-gulp-angular');

angularBuilder(gulp, {
  jsMain: 'path/to/js/main.js',
  cssMain: 'path/to/css/main.scss'
});

// Rest of your gulp file, potentially overwriting the angular builder 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)