README.md

Angular Express boilerplate to start a modern component driven Angular web application from scratch.

Features:

• automatic compilation of ES6 with Babel
• pre-configured package management using jspm
• dynamic module loading using the SystemJS dynamic ES6 loader
• pre-configured unit testing with karma, mocha, chai and PhantomJS
• powerful built-in server based on Express 4 and Harp with preprocessor support for Jade, Markdown, EJS, Coffeescript, Sass, LESS and Stylus.
• compile to HTML, CSS & JavaScript and host it anywhere

How to get started

Ensure the Angular Express CLI tool is installed:

$ npm install -g ngx-cli

Create a new project directory:

$ mkdir project
$ cd project

Initialize the boilerplate:

$ ngx init

Install third-party dependencies:

$ jspm install
$ npm install

Finally start the Angular Express server:

$ npm start

and navigate to: <ip>:9000 in the browser.

How the configuration works

The configuration is stored in configuration files in the /config directory.

It can be overriden and extended using the node-config rules:

# Default configuration
/config/default.js

# Production configuration
/config/production.js

# Local configuration
/config/local.js

See configuration files for more information.

How the Angular side works

The main JavaScript entry point for the Angular application is src/app.js:

import angular from "angular";
import c1 from 'components/sample-component/_build/index';

/**************************************************************************
 * Define Angular application
 *************************************************************************/

var ngModule = angular.module('app', []);

/**************************************************************************
 * Initialize components and pass component specific options
 *************************************************************************/

c1(ngModule, {baseUrl: '/components/sample-component'});

It uses ES6 syntax and promotes a component driven structure where each component is imported separately.

Components are then passed the Angular module and component specific options so they can dynamically configure themselves and attach them to the main Angular module.

The main markup entry point is src/index.jade. It dynamically loads app.js like this:

//- Non production environment
//- Load jspm loader and configuration
if environment !== "production"
    script(src="_jspm_packages/system.js")
    script(src="config.js")
    //- Bootstrap the application
    script.
        System.import('app');

//- Production environment
//- Load self executing bundle
if environment === "production"
    script(src="build.js")

and dependencies are loaded on demand.

In production mode, it loads the minified src/build.js to pre-load dependencies.

To generate the src/build.js, run:

$ npm run build

from the root of the project.

How to add components

Components are modules that contain their own:

• templates
• styles
• scripts
• assets
• unit tests

They are added to the src/components directory and imported in src/app.js.

Underscores

To include files that are not publicly accessible in production mode, prefix them with an _.

A good approach is to include a _build directory in a component to include files that should be available during development or build phase, but not during production.

See the included sample component for an example.

Adding existing components

To install existing components:

$ ngx install component-name

See the Angular Express component directory for a list of ready-to-use components.

To install custom components directly from a GitHub repository:

$ ngx install github-username/github-repository-name

See the Angular Express CLI documentation for more information.

How to start the server

Start the server:

# Uses NODE_ENV of your environment
$ npm start

Start the server in development mode:

# Uses NODE_ENV=development
$ npm run development-server

Start the server in production mode:

# Update src/build.js
$ npm run build

# Start production server
# Uses NODE_ENV=production
$ npm run production-server

How to compile to a static application

From the root of the project, run:

$ npm run compile

to compile static HTML, CSS and JavaScript in dist.

How to use livereload during development

Ensure you have BrowserSync installed:

$ npm install -g browser-sync

From the root of the project, run:

$ browser-sync start --proxy localhost:9000 --files "src/**/*"

and navigate your browser to the BrowserSync url:

 --------------------------------------
       Local: http://localhost:3000
 --------------------------------------
          UI: http://localhost:3001
 --------------------------------------

How to run unit tests

Make sure the Karma CLI is installed:

$ npm install -g karma-cli

To run the tests:

$ karma start

License

MIT

Change log

v0.2.0

• Added configuration support

v0.1.0

• Added modular structure