PWA Installation Guide for Aitana

This guide explains how to install the Aitana application as a Progressive Web App (PWA) on various devices.

Table of Contents

What is a PWA?

A Progressive Web App (PWA) is a web application that can be installed on your device and works offline. Aitana is built as a PWA, which means you can:

  • Install it on your desktop or mobile device
  • Use it offline (with cached content)
  • Launch it from your home screen or app drawer
  • Receive a native app-like experience

Here are some screenshots:

iOS app:

Desktop app:

Technical Implementation

Aitana implements PWA functionality through:

  • Service Worker (public/sw.js): Handles caching and offline functionality
  • Web App Manifest (src/app/manifest.json): Defines app metadata and appearance
  • Service Worker Registration: Automatically registered in src/app/layout.tsx

Installation Steps

Desktop Installation

Chrome/Edge:

  1. Visit the Aitana application in your browser
  2. Look for the install icon (⊕) in the address bar
  3. Click the icon and select “Install Aitana”
  4. The app will install and can be launched from your desktop

Firefox:

  1. Firefox doesn’t support PWA installation by default
  2. Use an extension like “PWA for Firefox” to enable PWA support

Safari (macOS):

  1. Open Aitana in Safari
  2. Click File → Add to Dock
  3. The app will be added to your dock

Mobile Installation

Android (Chrome):

  1. Open Aitana in Chrome
  2. You should see an “Add to Home Screen” banner
  3. If not, tap the menu (⋮) and select “Add to Home screen”
  4. Follow the prompts to install

iOS (Safari):

  1. Open Aitana in Safari
  2. Tap the Share button (□↑)
  3. Scroll down and tap “Add to Home Screen”
  4. Name the app and tap “Add”

Verifying Installation

After installation, you can verify the PWA is working correctly:

  1. Close the browser
  2. Launch Aitana from your app drawer/home screen
  3. The app should open in a standalone window
  4. Check offline functionality by disconnecting from the internet

Features Available in PWA Mode

When installed as a PWA, Aitana provides:

  • Standalone app window (no browser UI)
  • Offline access to cached content
  • Home screen/app drawer icon
  • Native-like experience
  • Automatic updates when online

Troubleshooting

Installation not offered

  • Ensure you’re using HTTPS (PWAs require secure contexts)
  • Check that the manifest.json is accessible at /manifest.json
  • Verify the service worker is registered (check browser console)

Service Worker issues

  • Clear browser cache and reload
  • Check browser console for errors
  • Ensure sw.js is in the public directory

iOS specific issues

  • Icons might not display correctly - ensure all required icon sizes are present
  • Status bar styling might not work as expected

For Developers

Testing PWA Installation

  1. Run the development server: npm run dev
  2. Use Chrome DevTools → Application tab to:
    • View the manifest
    • Check service worker status
    • Test offline functionality

Updating the PWA

To update the PWA configuration:

  1. Manifest changes: Edit src/app/manifest.json 
    {
  "name": "Aitana",
  "short_name": "Aitana",
  "description": "AI assistant for legal and contract work.",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#FF8C00",
  "icons": [...]
}
  2. Service Worker updates: Modify public/sw.js
    • Remember to increment the CACHE_NAME version
    • The service worker will auto-update when changed
  3. Icon requirements:
    • 192x192px (required)
    • 512x512px (recommended)
    • Additional sizes for iOS: 152x152, 180x180, 167x167

Building for Production

When building for production:

npm run build

The service worker and manifest will be included automatically.

Testing Offline Functionality

  1. Install the PWA
  2. Open Chrome DevTools → Network tab
  3. Select “Offline” checkbox
  4. Navigate through the app - cached pages should still load

Debugging Tips

  • Use Chrome’s Lighthouse tool to audit PWA compliance
  • Check Application tab in DevTools for manifest/service worker details
  • Monitor console for service worker lifecycle events
  • Test on real devices for best results

Additional Resources

Support

If you encounter issues with PWA installation or functionality, please:

  1. Check the browser console for errors
  2. Verify you’re using a supported browser
  3. Ensure you’re accessing the site via HTTPS
  4. Report issues to the development team