fabs - Fabulous AngularJS Build System

A Grunt based build system for AngularJS applications

Features:

• Dev-Mode with Server, Proxy and LiveReload
• SASS 3.2 and LESS 1.5 support
• Spec and End-2-End Test
• Mock Data for Tests and Dev-Mode
• Running Bower to Install and Update Frontend Dependencies
• Project- and Per-Developer Configuration as well as Command Line Arguments
• Building Distribution with
  • Embedding Templates and Translations
  • Annotating AngularJS Dependencies (Transform to Array-Notation)
  • Code Minimization
  • Cache Busting
  • Running End-2-End Tests Against Build Application

Getting Started

For a demo with project structure and fully configured build system, take a look at the companion project https://github.com/w11k/fabs-boilerplate

Installation

Add the grunt and fabs as dev dependencies to your package.json. Replace x with most recent or required version.

"grunt": "0.4.4",
"fabs": "x",

Add something like the following lines to your Gruntfile.js to include fabs's grunt configuration. Of course you are free to modify or extend the configuration object or merge it with other objects before registering it via grunt.initConfig.

var grunt = require('grunt');
var fabs = require('fabs');
var path = require('path');

module.exports = function () {
  // get absolute path to folder holding config files
  var configFolder = path.resolve('./build-config');

  var config = fabs.getGruntConfig(configFolder);
  grunt.initConfig(config);
};

Usage

Configuration

The build configuration used by fabs gets assembled by merging the internal 'system.config.js', a 'project.config.js' (required) and a 'developer.config.js' (optional). 'system.config.js' specifies all the properties the build system needs to run without errors. It tries to define some useful default but for all project you will need to adjust something.

Copy config-templates/project.config.tpl.js to your build-config folder (folder used in Gruntfile.js as parameter for fabs to load the configuration from) and adjust it to define your project configuration and override settings of 'system.config.js'.

The per developer configuration can be used to temporarily override some values (e.g. different proxy configuration to talk to a server running on your computer). Also, you can use developer.config.js to enable or disable some features of the build system during development like running 'bower install' on each start of grunt dev without adding --bower=false as command line argument all the time. Do not change the project configuration to adjust it to your personal needs during development. Use developer.config.js!

For documentation of build configuration properties, see 'src/system.config.js'.

Pay attention: the configurations (system, project and developer) get merged and merging doesn't extend but replace arrays!

Development

In dev mode for easy debugging the application's javascript files are neither concatenated nor minified. CSS code (form CSS files and generated from less or sass files) gets concatenated but not minified and will contains sass debug info. We have to concatenate CSS code to one file placed next to index.html, otherwise relative paths to assets won't work.

Run grunt dev to prepare the application, start the development server and watch for file changes. The application's code is copied to and served from build-output/prepared folder by default.

Pay attention: Watching for file changes does not include watching for new files on some systems / node versions. To ensure to collect all files kill and restart the dev server after creating a new file. Restart the dev server will be necessary too after changing the build configuration!

Build a distribution / deployable version

Run grunt dist to build a deployable version of the application, which is put to build-output/compiled folder by default and gets zipped to build-output/{{ Name and Version from package.json }}.zip

Hook into fabs lifecycle

fabs defines some empty dummy tasks at the beginning and the end of each phase (prepare and compile) and mode (dev and dist). You can use these hooks to add additional custom tasks.

Provided hooks:

• hookPrepareStart
• hookPrepareEnd
• hookCompileStart
• hookCompileEnd
• hookCacheBustingStart
• hookCacheBustingEnd
• hookDevStart
• hookDevEnd
• hookDistStart
• hookDistEnd

In your Gruntfile.js you can override these tasks. In the example below a replace task is added to replace a placeholder in a template file with the version number from package.json.

'use strict';

var grunt = require('grunt');
var fabs = require('fabs');
var path = require('path');
var lodash = require('lodash');
var pkg = grunt.file.readJSON('./package.json');

module.exports = function () {
  var configFolder = path.resolve('./build-config');
  var fabsConfig = fabs.getGruntConfig(configFolder);

  var additionalConfig = {
    replace: {
      version: {
        options: {
          prefix: '',
          patterns: [{
            match: '@@pkg.version',
            replacement: pkg.version,
            expression: false
          }]
        },
        files: [
          {
            expand: true,
            cwd: 'build-output/prepared',
            src: [ 'route/about/about.html' ],
            dest: 'build-output/prepared'
          }
        ]

      }
    }
  };
  
  var gruntConfig = lodash.merge(additionalConfig, fabsConfig);

  grunt.registerTask('hookPrepareEnd', ['replace:version']);
  grunt.initConfig(gruntConfig);
};

Other Tasks

In addition to grunt dev and grunt dist there are some other tasks meant to run stand-alone e.g. during release preparation.

• grunt bump: bumps the semver version number (see https://github.com/vojtajina/grunt-bump)
• grunt changelog: generates a changelog (see https://github.com/btford/grunt-conventional-changelog)

Roadmap

see milestones and issues at https://github.com/w11k/fabs/issues

License

MIT - see LICENSE file