build.md

Building your project's front end

Every CFPB project with a non-trivial front end should:

1. Use Grunt or Gulp to accomplish all front-end build tasks – example Gruntfile, example Gulpfile and Gulp scripts.
2. Use Less as a CSS preprocessor.
3. Use an optional config.json file in the project root to store build variables (internal API endpoints, PII, etc.). This file can be consumed by a Grunt/Gulp task and listed in .gitignore.
4. Require a maximum of three commands to install dependencies and build all static assets:
   1. npm install
   2. bower install (if necessary – many projects are transitioning away from Bower)
   3. grunt build or gulp build
5. These three commands (and any additional commands if there's a strong argument for them) should be stored in a setup.sh file (Grunt example, Gulp example) to make things easier for our CI environments.

You should avoid checking dependencies and minified assets into source control. It's common practice to keep development files in a src directory and compiled/minified assets in a gitignored dist directory.

Installing Node

Mac:

brew install node

Linux:

yum-config-manager --enable epel
yum install nodejs -y

Installing Grunt, Gulp and Bower

npm install -g grunt-cli gulp bower

Pegging versions

It's good practice to specify specific versions in any dependency management system such as maven, pip, ivy, npm, bower, etc. Yes, it incurs a bit of management overhead in that you have to manually change version numbers when you want to upgrade a dependency. This extra work pays off in absence of time spent tracking down unexpected changes or errors due to a version upgrade of which you were unaware.

When working with npm, we recommend using npm shrinkwrap.

Building JavaScript and Less

We usually use Grunt to automate the compilation of JavaScript and Less files. Some projects are transitioning to Gulp. Either is fine.

Here are some helpful plugins for Grunt:

• grunt-contrib-uglify for concatinating and minifying JS
• grunt-contrib-less for compiling Less and CSS files
• grunt-contrib-cssmin for minifying CSS
• grunt-contrib-clean for cleaning folders
• grunt-contrib-watch for watching and compiling assets on the fly
• grunt-browserify for using Node style CommonJS modules clientside

Capital Framework Generator

Our recommended workflow is to use the generator-cf Yeoman generator to scaffold out a new Capital Framework project. This generator provides a solid front-end build process and directory structure.

npm module generator

For authoring node modules, our recommended workflow is to use generator-node-cfpb. npm published modules should consist of tiny, reusable components. A general guideline is that if there is a bit of JavaScript that your app is using more than once, it would probably make a great npm published module.

To use the generator:

1. Install it by running: npm install -g generator-node-cfpb
2. cd into an empty directory, run this command and follow the prompts: yo node-cfpb