Simple yet Complete Angular Starter Project

26-02-2017
source code

Why another angular starter

Having seen most of the angular starters I decided to create this one for the following reasons

  • The most popular angular starter is full of features that you may not need for small or proof of concept projects
  • I didn't find a starter pack that combine simplicity with testing and production ready features

What is wrong with Angular CLI?

Nothing really. Angular CLI is an amazing tool to use, however if you want to understand how webpack works or if you want to try something new then this starter can be helpful in that regard.

Features

This angular starter contains the following features

Less noise

This starter doesn't try to cram every feature that is there into it but only provide what is necessary to start.

Tests included

This starter include fully functional unit, integration and e2e configuration.

Dev and Production ready

This angular starter has distinguished scripts to manage both dev and production environments

Easy to extend and change

This starter uses different configs for every environment, namely development, test and production. This made this starter easy to change and extend.

How to use

clone the repo then cd into the directory and issue the following command

npm install

To run the application issue the following command

npm run server

This will run the webpack-dev-server in a development mode. To run in production mode run the following command

npm run server:prod

Packages installed

The following tables contains the packages installed with this starter along with their purpose.

Dependencies


package name description
@angular/common commonly needed directives and services. include stuff like ngFor and ngSwitch
@angular/compiler the compiler library
@angular/core the core framework
@angular/platform-browser library for using Angular in a web browser
@angular/platform-browser-dynamic library for using Angular in a web browser with JIT compilation
@angular/router the routing library
core-js Standard library
rxjs Reactive Extensions for modern JavaScript
zone.js Zones for JavaScript

Dev Dependecies (Webpack)

These dev dependecies are for webpack.

package name description
@angular/compiler-cli required for @ngtools/webpack
@ngtools/webpack AOT plugin
awesome-typescript-loader typescript loader
copy-webpack-plugin copy files plugin
css-loader css loader
extract-text-webpack-plugin extract
html-webpack-plugin generate html file from a template
node-sass required for sass-loader
sass-loader load sass
style-loader load css styles in .css file and add link tag to html generated file
webpack webpack main package
webpack-dev-server webpack dev server

Dev Dependencies (Testing)

These dev dependencies are for testing.

package name description
@types/jasmine typings for Jasmine
jasmine Jasmine test framework
jasmine-spec-reporter this is used in protractor to display tests and their results
karma test runner
karma-chrome-launcher lunch chrome
karma-jasmine karma jasmine integration
karma-phantomjs-launcher launch phantomjs headless browser
karma-sourcemap-loader sourcemap loadr for karma, this is needed so the test result will show the typescript file line number not the transpiled js
karma-spec-reporter test reporter for karma
karma-webpack karma webpack integration
phantomjs-prebuilt phantomjs browser
protractor protractor
ts-node on the fly typescript transpiler. This is used to transpile e2e tests specs before running them

Dev Dependencies (Others)

package name description
@types/core-js typings for core-js package
rimraf delete tool
tslib Runtime library for TypeScript helper functions, this will allow us to remove ts-helpers package
typescript typescript

npm scripts

The following table shows the available scripts in package.config and their purpose

script name purpose
build Package the application using webpack.dev.js config file
server Packagethe application using webpack.dev.js config file and run the application using webpack-dev-server
build:prod Package the application using webpack.prod.js config file
server:prod Packagethe application using webpack.prod.js config file and run the application using webpack-dev-server
test:unit run unit test using karma
test:unit:watch run unit test using karma and keep watching for changes to run the test again
test:integration run integration test using karma
test:integration:watch run integration test using karma and keep watching for changes to run the test again
test:e2e run e2e tests

Folder structure

Image 1 shows the folder structure for this starter.

Project Structure

  • Config folder contains the webpack and karma config files. It also contains the e2e protractor config file. There is 2 separate entry files for the karma config, one for unit test and the other for integration test. The switch between them happened using NODE_ENV environment variable that we set in the npm script as follows.
    {
      "test:unit": "NODE_ENV=unit karma start ./config/karma/karma.conf.js",
      "test:unit:watch": "NODE_ENV=unit karma start ./config/karma/karma.conf.js --no-single-run --browsers=Chrome",
      "test:integration": "NODE_ENV=integration karma start ./config/karma/karma.conf.js",
      "test:integration:watch": "NODE_ENV=integration karma start ./config/karma/karma.conf.js --no-single-run --browsers=Chrome"
    }
  • The src folder contains the application code in the app folder as well as the assets folder which contains images and possibly other resources like fonts for example. The shared folder contains a ConsoleLogger service.

    note that there is no html file in the app folder because it will be generated using the template.html which is located in the config/webpack folder.

  • The test folder contains 3 folders for each test type. Note How the unit folder matches the app folder structure. This will make finding tests easier. The same thing should apply to integration test folder structure.

Conclusion

In this blog I went through an overview of the angular starter. This angular starter is simple yet complete with all the bits you need to start an angular project whether for a quick proof of concept example or for a production ready application.