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.
- 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 theapp
folder as well as the assets folder which contains images and possibly other resources like fonts for example. Theshared
folder contains aConsoleLogger
service.note that there is no html file in the
app
folder because it will be generated using thetemplate.html
which is located in theconfig/webpack
folder. - The
test
folder contains 3 folders for each test type. Note How the unit folder matches theapp
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.