Boilerplate for AngularJS Express

Zero configuration required!

This boilerplate combines all best practices of:

• the official Google recommended AngularJS application structure
• the fantastic AngularJS styleguide by Todd Motto
• the lovely HarpJS web server

and includes:

• Pre-configured AngularJS 1.3 application
• Pre-configured ui-router
• Pre-configured Gulpfile for concatenation, linting, unit testing, livereload and selectively copying bower component files
• Pre-configured Karma configuration for running unit tests
• HarpJS preprocessor support e.g. include a markdown file in your Jade file
• HarpJS compilation support to compile your application to a static version for deployment

Installation

First make sure you have the AngularJS Express CLI installed:

$ sudo npm install -g ngx-cli

Then initialize the boilerplate:

$ ngx init -b harp-angular-ui-router myproject

Change the directory to the new myproject directory:

$ cd myproject

Install the latest dependencies:

$ npm install
$ bower install

Run gulp to assemble the concatenated AngularJS library:

$ gulp

Start the harp server from your project directory:

$ harp server

And navigate to http://localhost:9000 in your browser:

Adding AngularJS Express components

Adding additional AngularJS Express components to your application is easy.

For example:

# Install a ui-router state not found handler component
$ ngx install ui-router-state-not-found-handler

# Install a ui-router state change error handler component
$ ngx install ui-router-state-change-error-handler

# Install less helper classes
$ ngx install less-padding-helper-classes

Components are downloaded from GitHub and installed in the public/components directory where you can customize it to your needs.

Check the official AngularJS Express components directory for all available components.

You can also easily include components from your own GitHub account like this:

# Install your custom component
$ ngx install github-username/component-repo-name

Check out the official AngularJS Express documentation for more info.

How it works

All action happens in the public directory, so let's have a look at its structure:

public
├── 200.jade
├── _build                          # main _build directory for global app stuff
│   ├── app.config.router.js        # Configure the router
│   ├── app.less                    # Global app styles that you want Gulp to add to /public/build/css/app.css
│   ├── app.module.js               # Main 'app' module
│   └── app.module.spec.js          # Sample unit tests for main 'app' module
├── build                           # Build directory where files built by Gulp are saved
│   ├── css
│   │   ├── app.css                 # All .less files from _build directories are concatenated here
│   │   └── app.min.css             # Minified version for production
│   └── js
│       ├── app.js                  # All .js files from _build directories are concatenated here
│       └── app.min.js              # Minified version for production
└── components
    ├── footer                      # Example footer component
    │   ├── _build                  # Component _build directory with files that you want Gulp to build
    │   │   └── footer.less         # Styles that you want to add to /public/build/css/app.css
    │   └── footer.jade             # Jade file will be compiled to HTML automatically
    ├── header                      # Example header component
    │   ├── _build                  # Component _build directory with files that you want Gulp to build
    │   │   └── header.less         # Styles that you want to add to /public/build/css/app.css
    │   └── header.jade             # Jade file will be compiled to HTML automatically
    └── homepage                    # Example homepage component
        ├── _build                  # Component _build directory with files that you want Gulp to build
        │   └── homepage.routes.js  # JavaScript code that you want to add to /public/build/js/app.js
        └── homepage.jade           # Jade file will be compiled to HTML automatically

Compiling to static

To build a static version for deployment, run:

$ harp compile . dist

This will create a dist directory with all files ready to be hosted statically.

Unit tests

Gulp is configured to automatically run all tests in public/**/_build/**/*.spec.js.

Gulp

Gulp is configured to:

• jshint all JavaScript files in the public directory
• concatenate all JavaScript files in all public/**/_build directories to public/build/js/app(.min).js
• concatenate all LESS files in all public/**/_build directories to public/build/css/app(.min).css
• selectively copy specific files from the Bower components to the public/vendor directory to prevent bloat that you don't want to push to your server
• run all JavaScript unit tests in all public/**/_build directories using Karma, Chai and Sinon

Changelog

v1.1.0

• Add livereload server
• Update documentation
• Update to Angular 1.3 by default

v1.0.0

• Refactor Grunt to Gulp
• Update documentation

v0.2.0

• Add Karma configuration
• Update documentation

v0.1.0

• Initial boilerplate