pwa.md

Progressive Web App (PWA) Configuration

This document provides comprehensive documentation for TuvixRSS's Progressive Web App capabilities, including installation, offline support, and modern PWA features.

Table of Contents

• Overview
• Features
  • Modern 2025 PWA Capabilities
  • Caching Strategies
• File Structure
• Development
  • Testing PWA Features Locally
  • Building for Production
  • Preview Production Build
• Icon Generation
• Installation
  • Desktop (Chrome/Edge/Brave)
  • Mobile (iOS Safari)
  • Mobile (Android Chrome)
• Manifest Configuration
  • Display Modes
  • App Shortcuts
  • Protocol Handlers
  • Share Target
  • Edge Side Panel
• Service Worker & Offline Support
  • Service Worker (Asset Caching)
  • React Query (Network-Aware Data Management)
  • Auto-updates
  • How They Work Together
• Customization
  • Theme Colors
  • Install Prompt Behavior
  • Caching Strategies
• Browser Support
  • Full PWA Support
  • Features by Browser
• Troubleshooting
• Monitoring
• Code References
• Resources

Overview

TuvixRSS is configured as a modern 2025 Progressive Web App with offline capabilities, installability, and enhanced mobile experience. The PWA implementation provides:

• Installable: Users can install the app on their devices (desktop, mobile, tablet)
• Offline Support: Core functionality works without internet connection
• Auto-updates: Service worker automatically updates when new versions are available
• App Shortcuts: Quick access to common actions from the home screen/start menu
• Protocol Handlers: Handle web+rss:// and feed:// protocol links
• Share Target: Receive shares from other apps on mobile devices

Features

Modern 2025 PWA Capabilities

• Installable: Users can install the app on their devices (desktop, mobile, tablet)
• Offline Support: Core functionality works without internet connection
• Auto-updates: Service worker automatically updates when new versions are available
• App Shortcuts: Quick access to common actions from the home screen/start menu
• Protocol Handlers: Handle web+rss:// and feed:// protocol links
• Share Target: Receive shares from other apps on mobile devices
• Window Controls Overlay: Modern desktop window appearance on supported platforms
• Maskable Icons: Adaptive icons that work across all platforms

Caching Strategies

The app uses intelligent caching strategies for optimal performance:

• Static Assets: Cache-first for CSS, JS, images (precached)
• API Calls: Network-first with 5-minute fallback cache
• External Fonts: Cache-first with 1-year expiration
• Images: Cache-first with 30-day expiration

File Structure

packages/app/
├── public/
│   ├── manifest.webmanifest      # Web app manifest with modern features
│   ├── browserconfig.xml         # Microsoft tile configuration
│   ├── icons/                    # Generated PWA icons
│   │   ├── icon-*x*.png          # Standard icons (72-512px)
│   │   ├── icon-maskable-*.png   # Maskable icons for adaptive displays
│   │   ├── apple-touch-icon.png  # Apple device icon (180x180)
│   │   └── shortcut-*.png        # Icons for app shortcuts
│   └── favicon.ico               # Browser favicon
├── src/
│   ├── hooks/
│   │   └── use-pwa-install.ts    # Hook for PWA installation logic
│   ├── components/
│   │   └── pwa-install-prompt.tsx # Install prompt UI component
│   └── pwa-register.ts           # Service worker registration
└── scripts/
    └── generate-icons.mjs        # Icon generation from SVG

Development

Testing PWA Features Locally

PWA features are enabled in development mode:

pnpm dev

The app will be available at http://localhost:5173 with service worker support.

Building for Production

pnpm build

The build process will:

1. Generate optimized service worker
2. Precache all static assets
3. Create manifest with correct asset paths

Preview Production Build

pnpm preview

This serves the production build locally to test PWA features.

Icon Generation

Icons are generated from the tuvixrss.svg logo:

pnpm generate:icons

This creates:

• Standard PWA icons (72x72 to 512x512)
• Maskable icons with safe zone padding
• Apple touch icon (180x180)
• Shortcut icons (96x96)
• Favicon (32x32)

To customize, edit scripts/generate-icons.mjs or replace the source SVG.

Installation

Desktop (Chrome/Edge/Brave)

1. Navigate to the app
2. Look for the install icon in the address bar
3. Click "Install" or use the install prompt
4. The app will open in its own window

Mobile (iOS Safari)

1. Open the app in Safari
2. Tap the Share button
3. Scroll down and tap "Add to Home Screen"
4. Tap "Add"

Mobile (Android Chrome)

1. Open the app in Chrome
2. Tap the three dots menu
3. Tap "Install app" or "Add to Home Screen"
4. Tap "Install"

Manifest Configuration

The manifest.webmanifest includes modern 2025 PWA features:

Display Modes

• window-controls-overlay: Modern desktop appearance
• standalone: Full-screen app experience
• minimal-ui: Minimal browser UI

App Shortcuts

Quick access to:

• View Feeds (/app/feeds)
• Unread Articles (/app/articles?filter=unread)
• Settings (/app/settings)

Protocol Handlers

• web+rss://: RSS protocol handler
• feed://: Feed protocol handler

Both redirect to /app/feeds/add?url=%s for easy feed subscription.

Share Target

The app can receive shares from other apps:

• Shared text, URLs, and titles
• Endpoint: /share-target (POST)
• Use case: Share articles/feeds from other apps

Edge Side Panel

Optimized for Microsoft Edge side panel:

• Preferred width: 400px
• Compact layout for side-by-side browsing

Service Worker & Offline Support

The app provides comprehensive offline support through two complementary systems:

Service Worker (Asset Caching)

• Cached static assets (JS, CSS, images) work offline
• API calls cached with 5-minute expiration
• Smart cache strategies per resource type
• Auto-cleanup of outdated caches

React Query (Network-Aware Data Management)

• Queries automatically pause when offline
• Polling stops to save battery/bandwidth
• Smart retry logic with exponential backoff
• Automatic data sync when reconnecting
• Previous data preserved during offline periods
• Clear UI feedback via offline indicator

See Offline Support Guide for detailed documentation on network-aware query management.

Auto-updates

• Checks for updates every hour
• Prompts user when new version is available
• Seamless update with page reload

How They Work Together

1. User goes offline:

   • Service worker serves cached app shell
   • React Query pauses all queries
   • Offline banner appears
   • Previous data remains visible

2. User comes back online:

   • Offline banner shows "Back online!"
   • React Query automatically refetches stale data
   • Service worker syncs new assets
   • Everything updates seamlessly

Customization

Theme Colors

Edit index.html and manifest.webmanifest:

<!-- index.html -->
<meta name="theme-color" content="#000000" />

// manifest.webmanifest
{
  "theme_color": "#000000",
  "background_color": "#000000"
}

Install Prompt Behavior

Edit src/components/pwa-install-prompt.tsx:

• Delay before showing: Change setTimeout delay (default: 3 seconds)
• Re-prompt interval: Modify daysSinceDismissed check (default: 7 days)
• UI customization: Update component JSX

Caching Strategies

Edit vite.config.ts workbox.runtimeCaching:

{
  urlPattern: /\/api\/.*/i,
  handler: "NetworkFirst", // or "CacheFirst", "StaleWhileRevalidate"
  options: {
    cacheName: "api-cache",
    expiration: {
      maxEntries: 100,
      maxAgeSeconds: 60 * 5, // 5 minutes
    },
  },
}

Browser Support

Full PWA Support

• Chrome/Edge/Brave: Desktop & Mobile
• Safari: iOS 11.3+ (with limitations)
• Firefox: Limited support
• Opera: Desktop & Mobile

Features by Browser

Feature	Chrome/Edge	Safari	Firefox
Install prompt	✅	iOS only	❌
Service worker	✅	✅	✅
Offline	✅	✅	✅
App shortcuts	✅	❌	❌
Protocol handlers	✅	❌	❌
Share target	✅	✅ (iOS)	❌
Window controls	✅	❌	❌

Troubleshooting

Service Worker Not Registering

1. Check console for errors
2. Ensure HTTPS (or localhost)
3. Clear browser cache and reload
4. Check DevTools > Application > Service Workers

Install Prompt Not Showing

1. App must be served over HTTPS
2. Must have valid manifest
3. Must have service worker
4. Chrome requires "engagement" (2 visits, 5 minutes apart)
5. User may have previously dismissed

Offline Not Working

1. Visit pages while online first (to cache)
2. Check Network tab in DevTools (throttle to offline)
3. Verify service worker is active
4. Check cache contents in Application tab

Icons Not Loading

1. Run pnpm generate:icons
2. Check public/icons/ directory
3. Verify paths in manifest.webmanifest
4. Clear browser cache

Monitoring

Service Worker Status

Open DevTools > Application > Service Workers to:

• View registration status
• Force update
• Skip waiting
• Unregister for testing

Cache Inspection

Open DevTools > Application > Cache Storage to:

• View cached resources
• Delete specific caches
• Monitor cache size

PWA Audit

Use Lighthouse in DevTools:

1. Open DevTools
2. Go to Lighthouse tab
3. Select "Progressive Web App"
4. Run audit

Target scores:

• PWA: 100/100
• Performance: 90+
• Accessibility: 90+

Code References

• Service Worker Registration: packages/app/src/pwa-register.ts
• PWA Install Hook: packages/app/src/hooks/use-pwa-install.ts
• Install Prompt Component: packages/app/src/components/pwa-install-prompt.tsx
• Manifest: packages/app/public/manifest.webmanifest
• Icon Generation: packages/app/scripts/generate-icons.mjs
• Vite PWA Config: packages/app/vite.config.ts (workbox configuration)

Resources

• MDN PWA Guide
• web.dev PWA
• Workbox Documentation
• vite-plugin-pwa
• Web App Manifest Spec