Helios

Initial Setup

1. Install node
2. On Mac: brew install node
3. On Windows: 1. Install NodeJS following these instructions 1. Install Python 2.7.10 from here 1. Install Microsoft C++ build tools. You can get it from the latest MS Visual Studio 2015 Community
4. Install global npm modules (grunt-cli, karma-cli, bower): npm install -g grunt-cli karma-cli bower
5. Change to the 'helios' directory
6. Install npm dependencies npm install
7. Install bower dependencies bower install
8. Make sure you have SaSS installed: gem install sass -g

Running the Application

You can run the application with mocked or real data.

Dev with Mocked Data

This takes less time to setup and run but uses mock data.

Run grunt mocks Open URL http://localhost:8000/

This serves the project files and the mocked backend data using Connect. It also hints, validates and runs tests on change. To add/update a cd-backend mock, simply update the test/mocks directory.

Dev with Real Data

This takes more time to setup and run but emulates the real environment.

1. Setup dev-environment.
2. Change to the helios directory.
3. Run grunt to lint, validate and runs tests on change.
4. View the project at http://localhost:8080.

Development on the Application

The Helios project uses Grunt for asset management, unit testing, serving assets locally, and overall developer convenience.

Summary

Grunt is a JavaScript task runner, not too different from Maven, Rake, Make, Gradle, etc. Grunt is installed via node package manager, which also handles dependency management for the project. If you are new to Grunt, you should take a look at the Grunt getting started guide.

Development

• Each time you pull new changes from master you should run npm install && bower install in the helios directory.
• You MUST have either grunt mocks or grunt dev active in your shell during front-end development.

Grunt Tasks

Below are a list of custom Grunt tasks. They are designed to make your life easier and your code better.

• grunt: Checks all files then produces a development build.
• grunt dev: Watches your project files and runs tests, hints, and validates on change.
• grunt test: Runs unit tests on JS files in Chrome.
• grunt mocks: Serves project files and cd-backend mocks. Also runs tests, hints, and validates on change.
• grunt check: Runs all checks for html, css, and js.
• grunt release: Creates a build for release.

The Build Pipeline

The build pipeline is automatically kicked off when you push a commit to the master branch of helios. Run all your checks (style and unit tests) locally via grunt check as the pipeline is dependent on these passing.

Bumping versions

The pushed commits automatically bump the patch level of this repo. The current checked in version is the expected next version of the app. Because the version number lives in multiple locations, it is recommended to use: grunt bump::minor (or major) to increment the version for semantic versioning requirements.

Updating Dependencies

Getting the latest and greatest shinny code is cool. Here are some basic guidelines:

• Run all tests and perform a manual regression (as needed) before submitting a pull request.
• Specify the complete version of dependencies (i.e. no *, ~, and such). This is to ensure a consistent experience for engineers and build servers.

npm

npm's dependencies--defined in package.json--are used by grunt to perform tasks. To check for updates, run npm outdated -depth=0. If you wish to update any NPM dependencies for the project, update package.json accordingly and run npm install. If you wish to update package.json install npm-check-updates by running npm install npm-check-updates

Bower

Bower's dependencies--defined in bower.json--are used for front-end asset management. To check for updates, run bower list. If you wish to update any bower dependencies for the project, update bower.json accordingly and run bower install. If Bower fails to download dependencies from git: but has success to download them via https: then you can apply the following command to tell git to do the substition for you:

git config --global url."https://".insteadOf git://

Practices showcased by this project

1. Modular approach of writing SPA-type (Single Page Applications) web Applications using AngularJS.
2. Feature-based directory structure minimizes impact of a change allowing multiple teams and individuals to work together without breaking each-other
3. Each feature folder can contain (optionally):
4. Controller (JS)
5. View (HTML)
6. Styles (additional to the main package or, in case of need, an overrides of the main guidelines) can be in the form: 1. CSS 1. SaSS - compiled on the fly if the file has .scss extension
7. External dependencies are hard versioned and managed by:
8. Bower through declarations in manifest ./bower.json for the web application
9. NPM through declarations in manifest package.json for the development environment. This covers all of the tools needed to build and test the application.
10. Main styles are provided by Bootstrap project.
11. To reduce the size of the initial download the application is broken into components that are lazy-loaded and composed in the browser by RequireJS on demand when user navigates to the view that hasn't been loaded yet
12. Application "fused" together by Angular UI Router which removes dependency on the URLs and replaces with navigation by parameter-driven "states"
13. Permalinks - each view state is represented by a full URL. URLs contain both information on the location and the selected data values.
14. Security - adding JWT to each passing HTTP request and modifying UI based on the claims and roles of the user
15. And much more:
16. Cache-busting (adds version to the URLs) - Static asset revisioning through file content hash 1. This updates accordingly JS/CSS links in the relevant HTML files
17. HTML templating (for parameter-driven HTML ./customization.json)
18. "Compilation" process of the web application - translates the original code (from ./app folder) into the final releasable structure (into ./dist folder)
19. usemin
20. modRewrite
21. RegureJS optimizer
22. HTML transformation 1. Linting 1. validation of HTML against W3C standards
23. Linting CSS
24. JavaScript transformation 1. Linting 1. Uglifying 1. Minifying
25. Testing 1. Automatic monitoring (watch) of the file-system and triggering automatic process when any of the relevant components changed 1. karma 1. e2e via protractor 1. Data mocking in the client 1. Mocking server responses
26. Release process 1. Packaging 1. Hard-Versionning (w/bumping - auto-increment) 1. Docker image (hard-versioned)

Notes

• Angular Seed: https://github.com/angular/angular-seed
• Angular best practices: http://blog.artlogic.com/2013/05/02/ive-been-doing-it-wrong-part-1-of-3/

For issues with npm install (likely caused when on WiFi) try:

git config --global url."https://".insteadOf git://

Source: bower/bower#50