angular2-webpack-seed (seed-webapp-1.0)
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
- gulpfile.babel.js - API proxy
- package.json - name, description, version
- karma.conf.js - jUnitReporter suite name
- webpack.config.dev.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 2 - as the Front-End framework
- Webpack 1 - Module loader / bundler, primary build tool
- Node 6 - local development and build time JavaScript runtime
- NPM 3 - package manager for build and application dependencies
- TypeScript 2.0 - 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
Links
- Repository (Github)- TODO: your-link-here
- Issue Tracker (JIRA) - TODO: your-link-here
- Documentation (Confluence) - TODO: your-link-here
- Continuous Integration (Jenkins) - TODO: your-link-here
- Development Environment - TODO: your-link-here
- Production Enviornment - TODO: your-link-here
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
Vagrant (optional)
Known Issue - thegreenhouseio#45 This project provides Vagrant to provision Virtual Machines for use with development. It is very easy to use
First, install the following
- Vagrant for replicating production environments locally for development. Version 1.7.4 required
- VirtualBox the tool used by Vagrant to spin up the local VM. Version >= 5.x required. Make sure to download guest additions as well.
- Vagrant Manager an OSX GUI tool for managing Vagrant instances (optional)
Steps for starting Vagrant
$ vagrant up$ vagrant ssh$ cd /vagrant
Manual
- If you don't already have it, download and install NodeJS (comes with NPM).
- This project favors version 3.x or higher, so make sure you have the latest by updating it after installing Node by running
$ npm install -g npm@3.8.8
- Now install the build and application dependencies by running
$ npm install(Vagrant will do this for you)
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 - NPM 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.dev.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, exectuted via NPM scripts. All available tasks are in the scripts
section of package.json
Development
This will start up a Node (Express) server which watches for changes and "redeploys" as needed.
$ npm run develop
See it in a browser by opening up
http://localhost:6789/
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 build a production version of the application.
$ npm run build
Note: This task exports NODE_ENV=production
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
$ npm run test
To run E2E tests, run:
$ npm run e2e
Note: E2E testing is not supported yet
Continuous Integration
This is a task for the CI server to run, generally called as part of a build script, in this case bin/build.sh. Run it using
$ npm run ci
This will run (in sequence) the build and test:unit tasks.
Note: This task exports NODE_ENV=production
Demo
To serve a production build locally , like for a demo run:
$ npm run demo
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
There are two types of dependencies tracked in the application
Node Modules
Build packages (like Webpack) are installed through NPM into package.json, using
$ npm install <package-name> --save-dev
Dependencies for the application (like Angular) are installed by running
$ npm install <some-package> --save
TypeScript Type Defintions
Typescript definitions provide type information for third-party packages and can be installed with NPM
$ npm install @type/{name} --save-dev
Then add that name to the compilerOptions.types array in tsconfig.json
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 -