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/[email protected] [email protected] [email protected] 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:

• [x] Crosswalk WebView
• [x] 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

• [x] Angular Ahead-Of-Time Compilation
• [x] Angular Lazy Loading Modules with PreloadAllModules Strategy
• [x] 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
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

# Run the Container
npm run docker.run

# Navigate to http://localhost

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

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

# Create Image and run Container
npm run docker.build && npm run docker.run

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:

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:

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