angular-enterprise-kickstar

An enterprise kickstarter for AngularJS+RequireJS projects.

Based on ngBoilerplate, RequireJS as one of key components, intelligent build system and best recommended web and angular libraries.

---

Quick Start

Install Node.js and then:

$ git clone git://github.com/kvindasAB/angular-enterprise-kickstart.git
$ cd angular-enterprise-kickstart
$ sudo npm -g install grunt-cli karma bower
$ npm install
$ bower install
$ ./node_modules/grunt-protractor-runner/node_modules/protractor/bin/webdriver-manager update
$ grunt watch

Finally, open http://localhost:8000 in your browser.

Purpose

angular-enterprise-kickstart main differences with ng-boilerplate.

• Require JS integration, optimization and minification.
• Modularization proposal based on AngularJS+RequireJS.
• Integration of E2E tests with Protractor.
• Separation of tests from application sources.
• Separation of styles from application sources.
• Updated to use the latest versions of both grunt plugins and bower libs.
• Added some core libs regularly used on enterprise development. Example: restangular, ng-table, momentjs, etc.
• WebServer functionality with rules.

Our scope probably is narrower than ngBoilerplate. We do not look out to be every AngularJS project kickstart, rather we look forward to be a base for those projects planning to use AngularJS+RequireJS. We have found RequireJS being beneficial on medium size projects where modularization and code scalability is a must.

Additional the project is inheriting all the benefits from ng-boilerplate as: Twitter Bootstrap, Angular UI, Angular Bootstrap, Font Awesome, and LESS. Lastly, it contains a sophisticated Grunt-based build system to ensure maximum productivity.

Philosophy

• RequireJS integration and modular app.
• Complete build system that does much of the usual required development tasks.
• Integration with popular tools like Bower, Karma, and LESS.
• Encourages test-driven development. It's the only way to code.
• Well-documented, to show new developers why things are set up the way they are.

Learn

Overall Directory Structure

At a high level, the structure looks roughly like this:

angular-enterprise-kickstart/
  |- grunt-tasks/
  |- src/
  |  |- app/
  |  |  |- <app logic>
  |  |  |- requirejs main config
  |  |- assets/
  |  |  |- <static files>
  |  |- common/
  |  |  |- <reusable code>
  |  |- less/
  |  |  |- main.less
  |- test/
  |  |- config/
  |  |  |- <test config files>
  |  |- unit/
  |  |  |- <unit test files>
  |  |- e2e/
  |  |  |- <e2e test files>
  |  |- requirejs test config
  |- vendor/
  |  |- angular-bootstrap/
  |  |- bootstrap/
  |  |- vendor files
  |- .bowerrc
  |- bower.json
  |- build.config.js
  |- Gruntfile.js
  |- package.json

What follows is a brief description of each entry, but most directories contain their own README.md file with additional documentation, so browse around to learn more.

• src/ - our application sources. Read more »
• test/ - our application tests and configuration. Read more »
• vendor/ - third-party libraries. Bower will install packages here. Anything added to this directory will need to be manually added to build.config.js and karma/karma-unit.js to be picked up by the build system.
• .bowerrc - the Bower configuration file. This tells Bower to install components into the vendor/ directory.
• bower.json - this is our project configuration for Bower and it contains the list of Bower dependencies we need.
• build.config.js - our customizable build settings; see "The Build System" below.
• Gruntfile.js - our build script; see "The Build System" below.
• package.json - metadata about the app, used by NPM and our build script. Our NPM dependencies are listed here.

Detailed Installation

This section provides a little more detailed understanding of what goes into getting angular-enterprise-kickstart up and running. Though the installation is really simple to use, it might help to have an understanding of the tools involved here, like Node.js and Grunt and Bower. If you're completely new to highly organized, modern JavaScript development, take a few short minutes to read this overview of the tools before continuing with this section.

Okay, ready to go? Here it is:

angular-enterprise-kickstart uses Grunt as its build system, so Node.js is required. Also, Grunt by default no longer comes with a command-line utility and Karma and Bower must end up in your global path for the build system to find it, so they must be installed independently. Once you have Node.js installed, you can simply use npm to make it all happen:

$ npm -g install grunt-cli karma bower

If you're on Linux (like I am) then throw sudo in front of that command. If you're on Windows, then you're on your own.

Next, you can either clone this repository using Git, download it as a zip file from GitHub, or merge the branch into your existing repository. Assuming you're starting from scratch, simply clone this repository using git:

$ git clone git://github.com/kvindasAB/angular-enterprise-kickstart.git my-project-name
$ cd my-project-name

And then install the remaining build dependencies locally:

$ npm install

This will read the dependencies (empty by default) and the devDependencies (which contains our build requirements) from package.json and install everything needed into a folder called node_modules/.

There are many Bower packages used by angular-enterprise-kickstart, like Twitter Bootstrap and Angular UI, which are listed in bower.js. To install them into the vendor/ directory, simply run:

$ bower install

In the future, should you want to add a new Bower package to your app, run the install command:

$ bower install packagename --save-dev

The --save-dev flag tells Bower to add the package at its current version to our project's bower.js file so should another developer download our application (or we download it from a different computer), we can simply run the bower install command as above and all our dependencies will be installed for us. Neat!

Technically, your project is now ready to go.

However, prior to hacking on your application, you will want to modify the package.json file to contain your project's information. Do not remove any items from the devDependencies array as all are needed for the build process to work.

To ensure your setup works, launch grunt:

$ grunt watch

The built files are placed in the build/ directory by default. Open the build/index.html file in your browser and check it out! Because everything is compiled, no XHR requests are needed to retrieve templates, so until this needs to communicate with your backend there is no need to run it from a web server.

watch is actually an alias of the grunt-contrib-watch that will first run a partial build before watching for file changes. With this setup, any file that changes will trigger only those build tasks necessary to bring the app up to date. For example, when a template file changes, the templates are recompiled and concatenated, but when a test/spec file changes, only the tests are run. This allows the watch command to complete in a fraction of the time it would ordinarily take.

In addition, if you're running a Live Reload plugin in your browser (see below), you won't even have to refresh to see the changes! When the watch task detects a file change, it will reload the page for you. Sweet.

When you're ready to push your app into production, just run the compile command:

$ grunt compile

This will concatenate and minify your sources and place them by default into the bin/ directory. There will only be three files: index.html, your-app-name.js, and your-app-name.css. All of the vendor dependencies like Bootstrap styles and AngularJS itself have been added to them for super-easy deploying. If you use any assets (src/assets/) then they will be copied to bin/ as is.

To run e2e tests run the task test:e2e. This task is not part of the compile or build tasks, so should be run manually:

$ grunt e2e

This will concatenate and minify your sources and place them by default into the bin/ directory. There will only be three files: index.html, your-app-name.js, and your-app-name.css. All of the vendor dependencies like Bootstrap styles and AngularJS itself have been added to them for super-easy deploying. If you use any assets (src/assets/) then they will be copied to bin/ as is.

Lastly, a complete build is always available by simply running the default task, which runs build and then compile:

$ grunt

The Build System

The best way to learn about the build system is by familiarizing yourself with Grunt and then reading through the heavily documented build script, Gruntfile.js. But you don't need to do that to be very productive. What follows in this section is a quick introduction to the tasks provided and should be plenty to get you started.

The driver of the process is the delta multi-task, which watches for file changes using grunt-contrib-watch and executes one of nine tasks when a file changes:

• delta:gruntfile - When Gruntfile.js changes, this task runs the linter (jshint) on that one file and reloads the configuration.
• delta:assets - When any file within src/assets/ changes, all asset files are copied to build/assets/.
• delta:html - When src/index.html changes, it is compiled as a Grunt template, so script names, etc., are dynamically replaced with the correct values configured dynamically by Grunt.
• delta:less - When any *.less file within src/ changes, the src/less/main.less file is linted and copied into build/assets/angular-enterprise-boilerplate.css.
• delta:jssrc - When any JavaScript file within src/ that does not end in .spec.js changes, all JavaScript sources are linted, all unit tests are run, and the all source files are re-copied to build/src.
• delta:coffeesrc - When any *.coffee file in src/ that doesn't match *.spec.coffee changes, the Coffee scripts are compiled independently into build/src in a structure mirroring where they were in src/ so it's easy to locate problems. For example, the file src/common/titleService/titleService.coffee is compiled to build/src/common/titleService/titleService.js.
• delta:tpls - When any *.tpl.html file within src/ changes, all templates are put into strings in a JavaScript file (technically two, one for src/common/ and another for src/app/) that will add the template to AngularJS's $templateCache so template files are part of the initial JavaScript payload and do not require any future XHR. The template cache files are build/template-app.js and build/template-common.js.
• delta:jsunit - When any *.spec.js file in test/unit/ changes, the test files are linted and the unit tests are executed.
• delta:coffeeunit - When any *.spec.coffee file in test/unit/ changes, the test files are linted, compiled their tests executed.

As covered in the previous section, grunt watch will execute a full build up-front and then run any of the aforementioned delta:* tasks as needed to ensure the fastest possible build. So whenever you're working on your project, start with:

$ grunt watch

And everything will be done automatically!

Build vs. Compile

To make the build even faster, tasks are placed into two categories: build and compile. The build tasks (like those we've been discussing) are the minimal tasks required to run your app during development.

Compile tasks, however, get your app ready for production. The compile tasks include concatenation, minification, compression, etc. These tasks take a little bit longer to run and are not at all necessary for development so are not called automatically during build or watch.

To initiate a full compile, you simply run the default task:

$ grunt

This will perform a build and then a compile. The compiled site - ready for uploading to the server! - is located in bin/, taking a cue from traditional software development. To test that your full site works as expected, open the bin/index.html file in your browser. Voila!

Live Reload!

angular-enterprise-kickstart also includes Live Reload, so you no longer have to refresh your page after making changes! You need a Live Reload browser plugin for this:

• Chrome - Chrome Webstore
• Firefox - Download from Live Reload
• Safari - Download from Live Reload
• Internet Explorer - Surely you jest.

Note that if you're using the Chrome version with file:// URLs you need to tell Live Reload to allow it. Go to Menu -> Tools -> Extensions and check the "Allow access to file URLs" box next to the Live Reload plugin.

When you load your page, click the Live Reload icon in your toolbar and everything should work magically.

If you'd prefer to not install a browser extension, then you must add the following to the end of the body tag in index.html:

<script src="http://localhost:35729/livereload.js"></script>

Roadmap

• We are still validating if continuing to use Grunt as our build system. Although Grunt has become a semi-standard building tool among javascript projects there are new alternatives such as Gulp, Brunch and recently Brocolli. We are also aware that the build system can be simpler than it is right now, both for this project and ngBoilerplate.
• We will also plan to build a small application example with this project to depict how to use the different technologies together.

To Do

See the issues list. And feel free to submit your own!

Contributing

Don't like the way I did something? Think you know of a better way? Have an idea to make this more useful? Let me know! You can contact me through all the usual channels or you can open an issue on the GitHub page. If you're feeling ambitious, you can even submit a pull request - how thoughtful of you!

So join the team! We're good people.