port-nimara-client-portal/docs/pwa-implementation.md

PWA Implementation Guide

Overview

The Port Nimara Portal has been implemented as a Progressive Web App (PWA) to provide users with a native app-like experience on mobile devices.

Features Implemented

1. PWA Configuration

• App Name: Port Nimara Portal
• Short Name: Port Nimara
• Theme Color: #387bca (brand primary color)
• Background Color: #ffffff
• Display Mode: standalone
• Start URL: /
• Icons: Multiple sizes from 72x72 to 512x512 pixels

2. Install Banner

• Location: Login page, below the login form
• Behavior:
  • Only shows on mobile devices
  • Hidden if app is already installed (standalone mode)
  • Shows only once (dismissal stored in localStorage)
  • Animated slide-in with 1-second delay

3. Installation Flow

• Android: Direct browser install prompt
• iOS: Step-by-step instructions modal
• Other browsers: Fallback instructions

4. Offline Support

• Service Worker: Auto-updating with Workbox
• Caching: Network-first for API calls, cache-first for assets
• Navigation Fallback: Routes to home page when offline

Files Added/Modified

New Files

• components/PWAInstallBanner.vue - Install banner component
• composables/usePWA.ts - PWA functionality composable
• plugins/pwa.client.ts - PWA initialization plugin
• docs/pwa-implementation.md - This documentation

Modified Files

• nuxt.config.ts - Added PWA configuration
• pages/login.vue - Added install banner component

Configuration Details

PWA Module Settings

pwa: {
  registerType: 'autoUpdate',
  manifest: {
    name: 'Port Nimara Portal',
    short_name: 'Port Nimara',
    description: 'Port Nimara Client Portal - Manage your berth interests and expressions of interest',
    theme_color: '#387bca',
    background_color: '#ffffff',
    display: 'standalone',
    orientation: 'portrait',
    start_url: '/',
    scope: '/',
    icons: [/* 8 icon sizes */]
  },
  workbox: {
    // Caching strategies
  }
}

Icon Requirements

The following icon sizes are configured:

• 72x72, 96x96, 128x128, 144x144 (Android)
• 152x152, 192x192 (iOS, Android)
• 384x384, 512x512 (Splash screens, large displays)

All icons are located in /public/icons/ and based on the circular Port Nimara logo.

Browser Support

• Chrome/Edge (Android): Full PWA support with install prompt
• Safari (iOS): Manual installation via "Add to Home Screen"
• Firefox: Basic PWA support
• Other browsers: Graceful degradation with instructions

Usage Instructions

For Users

1. Visit the login page on a mobile device
2. If eligible, an install banner will appear below the login form
3. Tap "Install App" to begin installation
4. Follow platform-specific instructions if needed

For Developers

The PWA functionality is automatically initialized. Use the usePWA() composable to access PWA state:

const { isInstalled, canInstall, install, isMobile, isIOS } = usePWA();

Testing

• Test on actual mobile devices for best results
• Use Chrome DevTools > Application > Manifest to verify configuration
• Check Service Worker registration in DevTools > Application > Service Workers
• Test offline functionality by disabling network

Deployment Notes

• Ensure HTTPS is enabled (required for PWA)
• Icons must be accessible via direct URLs
• Service worker will be auto-generated and registered
• Manifest will be auto-generated from nuxt.config.ts settings

Future Enhancements

• Push notifications
• Background sync
• App shortcuts
• Share target functionality
• Install banner in dashboard for non-mobile users