angular-webapp-seed

Angular 2 and Webpack Seed Project for The Greenhouse, as a template / starter project for frontend web applications. This is a simple starter project meant to get you up and running as fast as possible with a full local and production build with all the tools working together and as minimal friction and configuration as possible. Simply clone the repo and edit the files as needed to match your project.

This was based on the excellent starter AngularClass/angular2-webpack-starter as well as many other resources around the internet.

Note: A principal motivation in the direction and maintenance of this starter repo will be in support of adoption of latest standards and specifications of ECMAScript. For example, the decision to adopt Webpack was done with the understanding that ES6 imports and the System specification would be supported in the 2.0 release. This project will always strive to work as close to the spec as possible to ensure the least amount of tools get in the way between your user's browser and the source code written.

Setup

README.md - project name, Links, sections on release procedure, CI, AWS info
package.json - name, description, version, API proxy
karma.conf.js - jUnitReporter suite name
webpack.config.develop.js - devServer proxy value
Configure your project with continuous integration by running bin/build.sh

//TODO - discuss environment variables, continuous integration, AWS keys, build scripts

Tooling

The following tools are used in the application

Angular - as the Front-End framework
webpack 1 - Module loader / bundler, primary build tool
Node v6 - local development and build time JavaScript runtime
Yarn - package manager for build and application dependencies
TypeScript - superset of JavaScript for writing application code
Karma - task runner for unit and integration testing
Jasmine - testing framework
Bootstrap 4 (alpha) - Mobile first CSS framework

Project Setup

Note: It is recommended that a Javascript based IDE is used, like Webstorm, as they have a lot of the code quality and syntax tooling supported as plugins, often times right out of the box.

Recommended plugins to have are:

Git (can show changed lines in the gutter when viewing a file)
EditorConfig
gitignore
Sass
TypeScript
NodeJS

Installation

If you don't already have it, download and install NodeJS (which comes with NPM)
Make sure you have at least version >= 5

$ npm install -g yarn@^1.0.0 // may need sudo
$ yarn --version
1.1.0

Now install the project's dependencies by running $ yarn install

Project Layout

An overview of important files and configurations for the applications

Root Files

Also know as "dot" files, these are the build and build configuration files for the application

bin/ - shell scripts for continuous and build environments
.babelrc - Babel configuration file for supporting ES6 features gulpfile.js
.editorconfig - configuration file for EditorConfig IDE plugin
karma.conf.js - Karma configuration file
gulpfile.babel.js - Gulpfile for startting local production webserver
package.json - dependency configuration file, for build related dependencies and defines all runnable scripts and commands
tsconfig.json - TypeScript compiler configuration file
tslint.json - configuration rules for TS Lint
webpack.config.common.js - webpack config for managing shared webpack configurations
webpack.config.develop.js - webpack config for local development
webpack.config.prod.js - webpack config for production builds

Application Files

Application code, including unit tests. Directories are intended to be kept as flat as possible with a B.O.F. (birds of a feather) organization.

src - application code
src/components/ - resusable UI features
src/services/ - APIs for handling backend REST APIs or browser APIs, non UI related "helpers"
src/views/ - routable states ("pages")
src/index.html - main layout of the application
src/main.ts - main entry way into the application and Angular "bootstrapper" (@NgModule)
src/polyfills.ts - collection of polyfills needed by the application
src/routes.ts - routes for the application, maps to different views
src/vendor.ts - vendor files from node_modules

Tasks

This project uses Webpack as the build tool, executed via NPM scripts. All available tasks are in the scripts section of package.json

Development

This will start up Webpack's Dev Server which watches for changes and "redeploys" as needed.

$ yarn run develop

See it in a browser by opening up (should be automatic)

http://localhost:1981/

Note: This task exports NODE_ENV=development

Production

This is the production build task for the project. It is used prior to deploying to an environment and builds a production version of the application.

$ yarn run build

Testing

Testing is an important part of software development. There are three types of automated testing supported:

Unit - Used for testing discrete pieces of code in an isolated environemnt (i.e. mocked dependencies). Ideal for testing services and componengs.
Integration - Often we want to test how components and services behavior together without mocking. Integration testing is ideal for testing our view components.
E2E - End-to-End testing uses real browsers (often multiple) and aims to simulate real user ineractions with the application. This is done to validate our critical User Stories.

To run unit and integration tests, run

$ yarn run test

Continuous Integration / Delivery

For CI / CD, the production task is combined with the testing task with whatever other relevant post task is needed for that specific job's responsibility

$ export NODE_ENV=production
$ yarn run test
$ yarn run build

Serve / Run

To serve a production build locally, like for a demo run:

$ yarn run serve

Note: it is recommended you run this command from the master branch or a tag. By Default this proxies with the webpack-dev-server proxy.

Dependency Management

Build packages (like Webpack) are installed through Yarn into package.json, using

$ yarn add <package-name>  --dev

Dependencies for the application (like Angular) are installed by running

$ npm add <package-name>

Continuous Integration

//TODO Document Your Continuous Integration Environment Here

Release Procedure

//TODO Document Your Release Procedure Here

AWS Info

//TODO Document Your AWS Info here (NO CREDENTIALS!!!!)

s3 bucket -
cloudfront distribution -

thegreenhouseio/angular-webapp-seed