Angular PWA Seed

Description

Multiplatform Angular project (Web/PWA, Mobile and Desktop) with Ionic applied.

Sample

A sample is available at: https://angular-pwa-seed.netlify.com

TL;DR (Too Long; Didn't Read)

Just want to see this running on browser and android (if have the emulator already configured)!

At shell/cmd run this (windows only):

npm i -g yarn @angular/cli@1.7.1 cordova@6.5.0 ionic@2.2.3 typescript sleep-ms concurrently mkdirp && git clone https://github.com/jvitor83/angular-pwa-seed && cd angular-pwa-seed && npm install & (IF DEFINED ANDROID_HOME npm run install.android) & npm run start.cordova

Preview

Goal

Be the easiest, simplest, fastest and performative way to create a Web(PWA) using Angular.

Secondary goal

Allow optionally to create an installable application (and reach the maximum performance possible) using:

• Crosswalk WebView
• Simple layout (without complex animations/effects) based on Ionic - KISS

Features

• Multiplatform (Web, Mobile, Desktop) Cordova
• Multiples layouts out-of-box (Menu,Tab,Blank) (Ionic/Boostrap)
• Authentication/Authorization (OpenID/OAuth2)
• VSCode Integration (Debugger for Chrome, Cordova Tools)
• Angular CLI project (Generator commands)

Performance features

• Angular Ahead-Of-Time Compilation
• Angular Lazy Loading Modules with PreloadAllModules Strategy
• Progressive Web App Features - Manifest and Offline (for faster loading)

Developer Features

This Seed use Ionic to get the visual experience from each device/platform, be mobile friendly and performative. But it uses Ionic only at UI Components and Theming, the Router used is the Angular Router and not the Ionic's NavController.

• PWA Already - Manifest and ServiceWorker already configured (just need to host in HTTPS to get A2HS).

The service-worker (offline) is updated at each publish npm run publish.prod, so no worry about updating the cache version.

• Multiple Layouts - Choose between Menu, Tab and Blank Layouts

At app.html in <seed-layout type="menu">, choose your desired layout type

• Fast start - Just by giving the name, color theme and icon.

Change the config section at package.json, create your icon at resources/icon.png (for app) and assets/logo.png (for enterprise), then run npm run resources

• Debugging - Can debug easily

At VSCode, Run (debugging) just by pressing "F5"

• Simple responsive - Choose when hide or show elements (ex: if mobile or desktop).

Use the directive invisible-to="mobile" at any element/component to make it invisible when at mobile.

• Easy configuration - Use the Angular CLI environment.ts for app's configuration.
• Flexibe authentication/authorization - Authentication options is already setted (with google).

If you want login with your choosed OAuth2/OpenID Connect Identity Provider, just change the environment.ts config and use { provide: AUTH_SERVICE, useClass: OidcAuthService } at providers in app.module.ts (instead of YoloAuthService).

Another option is to use FirebaseAuthService already implemented/configured just by using { provide: AUTH_SERVICE, useClass: FirebaseAuthService } at providers in app.module.ts (instead of YoloAuthService).

You can easily implement your own Authentication Service just by extending the BaseAuthService<any> at base-auth.service.ts. An sample of this approach is at firebase-auth.service.ts

You can use the @Inject(AUTH_SERVICE) private authService: BaseAuthService<any> at your service/component constructor to get user infos at this.authService.auth.value.identity.user.name or by subscribing to it this.authService.auth.subscribe(auth => this.name = auth.identity.user.name);

• Fast development - Use the Angular CLI commands or AngularDoc VSCode Extension to generate your components/pages.

Ex: ng g component new-cmp. More info at Angular CLI

• Components you choose - It already has Ionic and Bootstrap installed, but you can include any other you want.

• Add PrimeNG components using this guide (Angular CLI Integration section)
• Add KendoUI components using this guide

• Container (Docker) - It already has Dockerfile to build and host the App. And includes npm scripts at package.json to manipulate the docker image and container.

Technologies

• Angular
• Angular CLI
• Ionic
• Cordova
• Boostrap
• Firebase
• OpenID/OAuth2 Client
• OpenYolo
• Docker

Requirements

• GIT: Have installed or Install GIT: https://git-scm.com/downloads
• NODE: Have installed or Install NODE (6+): https://nodejs.org/en/download/releases/
• Install Global Dependencies: npm install --global yarn @angular/[email protected] [email protected] [email protected] typescript sleep-ms concurrently mkdirp
• Install Platform Requirements (optional if other different than web): See the requirements at running section according to your chosen platform.

Starting

# Install global dependencies
npm install --global yarn @angular/[email protected] [email protected] [email protected] typescript sleep-ms concurrently mkdirp

# Clone this repo giving your new project name
git clone https://github.com/jvitor83/angular-pwa-seed.git [your-project-name]

cd [your-project-name]

# Set your origin repository (can be later if wanted to)
git remote set-url origin [your-project-git-repo]

# Add this repository as upstream (to keep updated)
git remote add upstream https://github.com/jvitor83/angular-pwa-seed.git

# Execute those always when want to get the latest updates from the seed
git fetch upstream
git merge upstream/master

# Install the project's dependencies
npm install

# (Optionally) Configure your project name, short_name and color at `package.json` and replace `./resources/icon.png` with the one of your project (must have 512x512)
npm run resources

# (Optionally) Start the project
npm run start

Container (Docker)

# Should already been cloned this repo

# Build the Docker Image that Build the App
npm run docker.build
# You can add special parameters to the build process to use some private Registry and Proxy like:
# npm run docker.build -- --build-arg registry=https://registry.npmjs.org/ --build-arg HTTP_PROXY=http://username:[email protected]:3128 --build-arg HTTPS_PROXY=http://username:[email protected]:3128

# Create the Container that will Build the App
npm run docker.run

# Tell the Container to Build the App
npm run docker.exec.script -- build.prod.aot

# Copy the files from the Container to the 'www' folder (at host)
npm run docker.copy

# Stop (Removing) the Build Container
npm run docker.stop

# Build the Docker Image that will Host the App
npm run docker.build.host

# Host the App (using NGINX)
npm run docker.run.host

# Navigate to http://localhost:5555

Docker command to Build and Host (Recreating the Image and Containers):

# Remove the Images and Containers (optional)
docker image rm angular-pwa-seed -f
docker image rm angular-pwa-seed-host -f

# Create Image, Container, Build and Host (in one line)
npm run docker.build && npm run docker.run && npm run docker.exec.script -- build.prod.aot && npm run docker.copy && npm run docker.stop && npm run docker.build.host && npm run docker.run.host

Running

You could use:

• Angular-CLI commands to get it running on web (ng serve) and/or
• Cordova commands to get it running at others platforms (cordova platform add android && cordova run android).

Only remember to first build the angular ng build , then run the cordova cordova run android.

So, the steps are:

Web	Other Platforms (Cordova)
- Run ng serve	- Compile the App ng build
	- Install your desired platform (one time only) cordova platform add android --save
	- Run your desired platform cordova run android

VSCode: Running on Web: Just press F5

Requirements:

Each platform has your specific requirements (SDK, Tools, environment) to compile/run.

- Ex: To compile/run android, must have Android Studio or Android SDK installed and a emulator or device.

- Ex: To compile windows, must have Visual Studio and be on windows to run.

See the links below to know how to install each requirement.

You could use some custom npm scripts/commands to install/run the platform:

PLATFORM	REQUIREMENTS/GUIDE (Tools, Sdk, etc)	INSTALL	RUN
Web			npm run start
Android	Platform Guide	npm run install.android	npm run start.android
IOS	Platform Guide	npm run install.ios	npm run start.ios
Windows	Platform Guide	npm run install.windows	npm run start.windows
OSx	Platform Guide	npm run install.osx	npm run start.osx
Ubuntu (Linux)	Platform Guide	npm run install.ubuntu	npm run start.ubuntu
Browser		npm run install.browser	npm run start.browser

Multiplatform

You can try multiple platform at same time using:

• Open shell then run npm run start.mobile

If you want to see it in a non-web emulator, then run npm run start.cordova

It is highly recommended to use Genymotion for Android Emulation.

Structure

├── src                             <- source code of the application
│   ├── app                         <- angular components

More details at: Angular CLI and Ionic

AddOns

IDE:

- Recommended extensions:

• Debugger for Chrome
• Angular Language Services
• AngularDoc for Visual Studio Code
• Auto Import
• Cordova Tools
• Angular Snippets
• Ionic 2 Snippets
• Ionic 2 Commands
• Bootstrap 3 Snippets or Bootstrap 4 Snippets

Testing:

- Testing against multiple browsers/platforms