Ionic 8 + Angular Boilerplate

A modern mobile application built with Ionic 8 frontend and Angular 20. Supports Android, iOS, and Progressive Web App (PWA) deployment with JWT authentication, offline capabilities, and native device features.

📋 Prerequisites

Before you begin, ensure your system meets these requirements:

System Requirements

Operating System: Windows 10/11, macOS 12+, or Linux (Ubuntu 20.04+)
RAM: Minimum 8GB (16GB recommended)
Disk Space: 10GB free space
Internet: Stable broadband connection

Required Software Versions

Software	Version	Purpose
Node.js	18.0.0+	JavaScript runtime
npm	8.0.0+	Package manager
Angular CLI	20.0.0+	Angular development tools
Ionic CLI	7.0.0+	Ionic development tools
Capacitor CLI	7.4.3+	Native runtime tools
Java JDK	11+ (Android only)	Android development
Android Studio	2022+ (Android only)	Android IDE and SDK
Xcode	14+ (macOS only)	iOS development

🚀 Quick Start - Local Development (Web/PWA)

Step 1: Install Prerequisites

Install Node.js and npm

# Download and install from https://nodejs.org/
# Or using package manager:

# Windows (using Chocolatey)
choco install nodejs

# macOS (using Homebrew)
brew install node

# Linux (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

Verify installation:

node --version    # Should show v18.x.x or higher
npm --version     # Should show 8.x.x or higher

Install Angular CLI

npm install -g @angular/cli@20
ng version         # Should show Angular CLI 20.x.x

Install Ionic CLI

npm install -g @ionic/cli@7
ionic --version    # Should show 7.x.x

Step 2: Clone and Setup Project

# Clone the repository
git clone <your-repository-url> ionic-app
cd ionic-app

# Install project dependencies
npm install

# Verify installation
npm list --depth=0

Step 3: Configure Environment

Local Development Environment

File: src/environments/environment.ts

export const environment = {
  production: false,
  apiUrl: 'http://localhost:8000',  // Your backend API URL
  corsBypass: true
};

UAT Environment

File: src/environments/environment.uat.ts

export const environment = {
  production: false,
  apiUrl: 'https://uat1.demo.com'  // Your UAT backend URL
};

Production Environment

File: src/environments/environment.prod.ts

export const environment = {
  production: true,
  apiUrl: 'https://app.demo.com'  // Your production backend URL
};

Step 4: Configure Proxy (for Local Development)

File: proxy.conf.json

{
  "/simulator-services/*": {
    "target": "http://localhost:8000",
    "secure": false,
    "changeOrigin": true,
    "logLevel": "debug"
  },
  "/simulator/*": {
    "target": "http://localhost:8000",
    "secure": false,
    "changeOrigin": true,
    "logLevel": "debug"
  }
}

Step 5: Run Local Development Server

# Start development server with proxy
ng serve

# Or use Ionic CLI
ionic serve

# Access the app at: http://localhost:4200

Step 6: Run Tests (Optional)

# Run unit tests
npm test

# Run tests with coverage
npm run test:coverage

# Run linting
npm run lint

📱 Android Setup and Development

Step 1: Install Java Development Kit (JDK)

# Download from https://adoptium.net/
# Or using package manager:

# Windows/macOS: Download and install JDK 11 or 17
# Linux:
sudo apt update
sudo apt install openjdk-11-jdk

Verify installation:

java -version     # Should show Java 11 or 17
javac -version    # Should show javac 11.x.x or 17.x.x

Step 2: Install Android Studio

Download Android Studio
- Visit: https://developer.android.com/studio
- Download the latest stable version
Install Android Studio
- Run the installer
- Select "Standard" installation
- Wait for SDK components to download
Configure Android SDK
- Open Android Studio
- Go to File > Settings > Appearance & Behavior > System Settings > Android SDK
- Install:
  - Android 13.0 (API 33) or later
  - Android SDK Build-Tools 33.0+
  - Android SDK Platform-Tools
  - Android Emulator
  - Google Play services

Step 3: Configure Environment Variables

Windows

# Open Command Prompt as Administrator
setx ANDROID_HOME "C:\Users\%USERNAME%\AppData\Local\Android\Sdk"
setx PATH "%PATH%;%ANDROID_HOME%\platform-tools;%ANDROID_HOME%\tools;%ANDROID_HOME%\tools\bin"

# Restart Command Prompt and verify
echo %ANDROID_HOME%
adb version

macOS/Linux

# Add to ~/.bashrc or ~/.zshrc
export ANDROID_HOME=$HOME/Library/Android/sdk  # macOS
# OR
export ANDROID_HOME=$HOME/Android/Sdk          # Linux

export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin

# Reload shell
source ~/.bashrc

Step 4: Add Android Platform to Project

# Navigate to project directory
cd ionic-app

# Add Android platform
npx cap add android

# Sync web assets to Android project
npx cap sync android

Step 5: Configure Android Permissions

File: android/app/src/main/AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Network permissions -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    <!-- Camera permissions -->
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-feature android:name="android.hardware.camera" android:required="false" />

    <!-- Location permissions -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

    <!-- Push notification permissions -->
    <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme"
        android:usesCleartextTraffic="true">

        <!-- Main Activity -->
        <activity
            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale"
            android:label="@string/title_activity_main"
            android:launchMode="singleTask"
            android:name=".MainActivity"
            android:theme="@style/AppTheme.NoActionBarLaunch"
            android:exported="true">

            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

Step 6: Build Android APK

# Build web assets for production
ng build

# Sync to Android project
npx cap sync android

# Open in Android Studio
npx cap open android

Step 7: Run on Android Device/Emulator

Using Android Studio

Open Android Studio (from npx cap open android)
Select device/emulator from toolbar
Click Run button (green play icon)

Using Command Line

# Run on connected device
npx cap run android

# Run on specific device
npx cap run android --target=<device-id>

# List available devices
adb devices

Step 8: Generate Production APK

# Build release APK
npx cap build android

# In Android Studio:
# Build > Build Bundle(s)/APK(s) > Build APK(s)
# Find APK at: android/app/build/outputs/apk/release/

🍎 iOS Setup and Development (macOS Only)

Step 1: Install Xcode

Open App Store on your Mac
Search for "Xcode"
Click Get and wait for download/installation
Launch Xcode and accept license agreement

Alternative: Download from developer.apple.com

Step 2: Install Command Line Tools

# Install Xcode command line tools
xcode-select --install

# Accept Xcode license
sudo xcodebuild -license accept

Verify installation:

xcodebuild -version    # Should show Xcode 14.x.x
xcode-select -p        # Should show /Applications/Xcode.app/Contents/Developer

Step 3: Install CocoaPods (Dependency Manager)

# Install CocoaPods
sudo gem install cocoapods

# Verify installation
pod --version

Step 4: Set Up Apple Developer Account

Visit: https://developer.apple.com/
Sign up for Apple Developer Program ($99/year)
Create App ID and Provisioning Profiles
Generate Certificates for code signing

Step 5: Add iOS Platform to Project

# Navigate to project directory
cd ionic-app

# Add iOS platform
npx cap add ios

# Sync web assets to iOS project
npx cap sync ios

Step 6: Configure iOS Permissions

File: ios/App/App/Info.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <!-- Basic App Information -->
    <key>CFBundleDisplayName</key>
    <string>Ionic App</string>
    <key>CFBundleIdentifier</key>
    <string>com.yourcompany.yourapp</string>
    <key>CFBundleShortVersionString</key>
    <string>1.0.0</string>
    <key>CFBundleVersion</key>
    <string>1</string>

    <!-- iOS Version Requirements -->
    <key>LSMinimumSystemVersion</key>
    <string>12.0</string>
    <key>UIRequiredDeviceCapabilities</key>
    <array>
        <string>arm64</string>
    </array>

    <!-- Network Permissions -->
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsArbitraryLoads</key>
        <true/>
        <key>NSAllowsLocalNetworking</key>
        <true/>
    </dict>

    <!-- Camera Permissions -->
    <key>NSCameraUsageDescription</key>
    <string>This app needs camera access to take photos</string>
    <key>NSPhotoLibraryUsageDescription</key>
    <string>This app needs photo library access to select images</string>

    <!-- Location Permissions -->
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>This app needs location access for location-based features</string>
    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
    <string>This app needs background location access</string>

    <!-- Push Notification Permissions -->
    <key>UIBackgroundModes</key>
    <array>
        <string>remote-notification</string>
    </array>

    <!-- Orientation Support -->
    <key>UISupportedInterfaceOrientations</key>
    <array>
        <string>UIInterfaceOrientationPortrait</string>
        <string>UIInterfaceOrientationLandscapeLeft</string>
        <string>UIInterfaceOrientationLandscapeRight</string>
    </array>
</dict>
</plist>

Step 7: Configure Code Signing

Open in Xcode:
```
npx cap open ios
```
Select Development Team:
- In Xcode, select your project
- Go to Signing & Capabilities
- Select your Apple Developer account
- Choose appropriate provisioning profile
Update Bundle Identifier:
- Ensure it matches your App Store Connect app

Step 8: Build iOS App

# Build web assets for production
ng build

# Sync to iOS project
npx cap sync ios

# Open in Xcode
npx cap open ios

Step 9: Run on iOS Device/Simulator

Using Xcode

Open Xcode (from npx cap open ios)
Select device/simulator from toolbar
Click Run button (play icon)

Using Command Line

# Run on connected device
npx cap run ios

# Run on specific simulator
npx cap run ios --target="iPhone 14"

# List available simulators
xcrun simctl list devices

Step 10: Generate Production IPA

# Build for release
npx cap build ios

# In Xcode:
# 1. Select "Any iOS Device" as target
# 2. Go to Product > Archive
# 3. Wait for archive to complete
# 4. Export IPA for App Store submission

🌐 PWA Setup and Deployment

Step 1: Configure PWA Manifest

File: src/manifest.json

{
  "name": "Ionic App",
  "short_name": "IonicApp",
  "description": "A modern web application built with Ionic",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#3880ff",
  "orientation": "portrait-primary",
  "scope": "/",
  "lang": "en-US",
  "icons": [
    {
      "src": "assets/icon/icon-72x72.png",
      "sizes": "72x72",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "assets/icon/icon-96x96.png",
      "sizes": "96x96",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "assets/icon/icon-128x128.png",
      "sizes": "128x128",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "assets/icon/icon-144x144.png",
      "sizes": "144x144",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "assets/icon/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "assets/icon/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable any"
    }
  ],
  "categories": ["business", "productivity"],
  "screenshots": [
    {
      "src": "assets/screenshots/screenshot1.png",
      "sizes": "1280x720",
      "type": "image/png",
      "label": "App Homepage"
    }
  ]
}

Step 2: Configure Service Worker

File: ngsw-config.json

{
  "$schema": "./node_modules/@angular/service-worker/config/schema.json",
  "index": "/index.html",
  "assetGroups": [
    {
      "name": "app",
      "installMode": "prefetch",
      "resources": {
        "files": [
          "/favicon.ico",
          "/index.html",
          "/manifest.json",
          "/*.css",
          "/*.js"
        ]
      }
    },
    {
      "name": "assets",
      "installMode": "lazy",
      "updateMode": "prefetch",
      "resources": {
        "files": [
          "/assets/**",
          "/*.(eot|svg|cur|jpg|png|webp|gif|otf|ttf|woff|woff2|ani)"
        ]
      }
    }
  ],
  "dataGroups": [
    {
      "name": "api-performance",
      "urls": ["/api/**"],
      "cacheConfig": {
        "strategy": "performance",
        "maxSize": 100,
        "maxAge": "1h"
      }
    }
  ]
}

Step 3: Update index.html for PWA

File: src/index.html

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="utf-8" />
  <title>Ionic App</title>

  <base href="/" />

  <meta name="viewport" content="viewport-fit=cover, width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <meta name="format-detection" content="telephone=no" />
  <meta name="msapplication-tap-highlight" content="no" />

  <!-- PWA Meta Tags -->
  <meta name="theme-color" content="#3880ff" />
  <meta name="apple-mobile-web-app-capable" content="yes" />
  <meta name="apple-mobile-web-app-status-bar-style" content="default" />
  <meta name="apple-mobile-web-app-title" content="Ionic App" />

  <!-- Favicon and Icons -->
  <link rel="icon" type="image/png" sizes="32x32" href="assets/icon/favicon.png" />
  <link rel="apple-touch-icon" href="assets/icon/icon-192x192.png" />
  <link rel="manifest" href="manifest.json" />

  <!-- Preload critical resources -->
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
</head>

<body>
  <app-root></app-root>
</body>

</html>

Step 4: Build for PWA

# Build for production with PWA support
ng build

# The build output will be in 'www/' directory
# Service worker and web app manifest are automatically included

Step 5: Test PWA Locally

# Install http-server globally
npm install -g http-server

# Serve the built app
http-server www -p 8080 -c-1

# Open browser to http://localhost:8080
# Use Chrome DevTools > Lighthouse to test PWA features

Step 6: Deploy PWA

Option 1: Firebase Hosting

# Install Firebase CLI
npm install -g firebase-tools

# Login and initialize
firebase login
firebase init hosting

# Deploy
firebase deploy

Option 2: Vercel

# Install Vercel CLI
npm install -g vercel

# Deploy
vercel --prod

Option 3: Netlify

# Install Netlify CLI
npm install -g netlify-cli

# Deploy
netlify deploy --prod --dir=www

🔧 Environment Configuration

Switching Between Environments

# Development (default)
ng serve

# Production build
ng build

# Watch mode
ng build --watch --configuration development

Environment Files

environment.ts - Local development
environment.uat.ts - User Acceptance Testing
environment.prod.ts - Production

🧪 Testing

Run Unit Tests

# Run all tests
npm test

# Run tests once (CI mode)
npm run test:ci

# Run with coverage
npm run test:coverage

Run E2E Tests

# Install Cypress (if not included)
npm install cypress --save-dev

# Run E2E tests
npx cypress run

Code Quality

# Lint code
npm run lint

# Format code
npm run format

# Run all quality checks
npm run quality

📦 Build Commands

Web/PWA Builds

# Development build
ng build

# Production build
ng build

# Watch mode
ng build --watch --configuration development

Native Builds

# Android build
ng build
npx cap sync android
npx cap open android

# iOS build
ng build
npx cap sync ios
npx cap open ios

🚀 Deployment

Web/PWA Deployment

# Build for production
ng build

# Deploy to your hosting service
# Options: Firebase, Vercel, Netlify, AWS S3, etc.

Android Deployment

# Build and sync
ng build
npx cap sync android

# Generate signed APK/AAB in Android Studio
# Upload to Google Play Store

iOS Deployment

# Build and sync
ng build
npx cap sync ios

# Archive in Xcode
# Upload to App Store Connect

📋 Quick Setup Checklist

For All Platforms

Node.js 18+ installed
Angular CLI 20+ installed
Ionic CLI 7+ installed
Project cloned and dependencies installed
Environment files configured
Development server runs without errors

For Android Development

For iOS Development

For PWA Development

Web app manifest configured
Service worker enabled
HTTPS enabled for production
Icons and splash screens added

🔧 Troubleshooting

Common Issues

Build Errors

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Platform Sync Issues

# Clean and resync
npx cap clean
npx cap sync

Environment Issues

# Check environment files
cat src/environments/environment.ts

Port Conflicts

# Use different port
ng serve --port=4201

📚 Documentation

Complete Documentation: See /docs folder
Ionic Documentation: https://ionicframework.com/docs
Angular Documentation: https://angular.io/docs
Capacitor Documentation: https://capacitorjs.com/docs

📞 Support

Documentation: Check /docs folder first
Issues: Create GitHub issue with detailed information
Community: Ionic Discord or Stack Overflow

🎯 Success Criteria

✅ Local Development: App runs at http://localhost:4200 ✅ Android: APK generated and runs on device/emulator ✅ iOS: IPA generated and runs on device/simulator ✅ PWA: Lighthouse PWA score > 90 ✅ Build: All platforms build successfully ✅ Tests: Unit tests pass with good coverage

Ready to start developing! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.vscode		.vscode
android/app		android/app
docs		docs
ios/App/App		ios/App/App
resources		resources
src		src
.browserslistrc		.browserslistrc
.editorconfig		.editorconfig
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
ICONS_SPLASH_README.md		ICONS_SPLASH_README.md
README.md		README.md
angular.json		angular.json
capacitor.config.ts		capacitor.config.ts
ionic.config.json		ionic.config.json
karma.conf.js		karma.conf.js
package-lock.json		package-lock.json
package.json		package.json
proxy.conf.json		proxy.conf.json
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.spec.json		tsconfig.spec.json

krguptaa/ionic-angular-boilerplate

Folders and files

Latest commit

History

Repository files navigation

Ionic 8 + Angular Boilerplate

📋 Prerequisites

System Requirements

Required Software Versions

🚀 Quick Start - Local Development (Web/PWA)

Step 1: Install Prerequisites

Install Node.js and npm

Install Angular CLI

Install Ionic CLI

Step 2: Clone and Setup Project

Step 3: Configure Environment

Local Development Environment

UAT Environment

Production Environment

Step 4: Configure Proxy (for Local Development)

Step 5: Run Local Development Server

Step 6: Run Tests (Optional)

📱 Android Setup and Development

Step 1: Install Java Development Kit (JDK)

Step 2: Install Android Studio

Step 3: Configure Environment Variables

Windows

macOS/Linux

Step 4: Add Android Platform to Project

Step 5: Configure Android Permissions

Step 6: Build Android APK

Step 7: Run on Android Device/Emulator

Using Android Studio

Using Command Line

Step 8: Generate Production APK

🍎 iOS Setup and Development (macOS Only)

Step 1: Install Xcode

Step 2: Install Command Line Tools

Step 3: Install CocoaPods (Dependency Manager)

Step 4: Set Up Apple Developer Account

Step 5: Add iOS Platform to Project

Step 6: Configure iOS Permissions

Step 7: Configure Code Signing

Step 8: Build iOS App

Step 9: Run on iOS Device/Simulator

Using Xcode

Using Command Line

Step 10: Generate Production IPA

🌐 PWA Setup and Deployment

Step 1: Configure PWA Manifest

Step 2: Configure Service Worker

Step 3: Update index.html for PWA

Step 4: Build for PWA

Step 5: Test PWA Locally

Step 6: Deploy PWA

Option 1: Firebase Hosting

Option 2: Vercel

Option 3: Netlify

🔧 Environment Configuration

Switching Between Environments

Environment Files

🧪 Testing

Run Unit Tests

Run E2E Tests

Code Quality

📦 Build Commands

Web/PWA Builds

Native Builds

🚀 Deployment

Web/PWA Deployment

Android Deployment

iOS Deployment

📋 Quick Setup Checklist

For All Platforms

For Android Development

For iOS Development

For PWA Development

🔧 Troubleshooting

Common Issues

📚 Documentation

Packages