Progressive Web App (PWA) Features
Relevant source files
The following files were used as context for generating this wiki page:
- src/components/PwaInstallCard.tsx
- src/lib/theme-site-identity.ts
- src/app/[locale]/admin/(general)/_actions/update-general-settings.ts/_actions/update-general-settings.ts)
- src/app/[locale]/admin/(general)/_components/AdminGeneralSettingsForm.tsx/_components/AdminGeneralSettingsForm.tsx)
- src/app/[locale]/(platform)/_components/HeaderDropdownUserMenuGuest.tsx/_components/HeaderDropdownUserMenuGuest.tsx)
- tests/unit/themeSiteIdentity.test.ts
The Progressive Web App (PWA) features within the prediction market platform enable users to install the web application as a native-like app on their mobile or desktop devices. This system provides a non-intrusive installation flow, localized installation instructions, and customizable branding through managed assets such as icons and theme colors.
The PWA implementation relies on a combination of client-side hooks to manage the installation prompt, UI components for user interaction (cards and dialogs), and an administrative backend for managing PWA-specific assets like the 192x192 and 512x512 manifest icons.
PWA Asset Management
The platform allows administrators to configure PWA-specific identity assets via the Admin General Settings. These assets are essential for the Web App Manifest, determining how the application appears on a user's home screen or app drawer.
Technical Specifications for Assets
The system enforces specific constraints on PWA icons during the upload process to ensure compatibility across devices.
| Asset Type | Required Dimension | Max File Size | Accepted Formats |
|---|---|---|---|
| Small PWA Icon | 192x192 px | 2 MB | PNG, JPG, WebP, SVG |
| Large PWA Icon | 512x512 px | 2 MB | PNG, JPG, WebP, SVG |
| Apple Touch Icon | 192x192 px | N/A | Derived from Small PWA Icon |
Sources: src/app/[locale]/admin/(general)/_actions/update-general-settings.ts:25-26, src/lib/theme-site-identity.ts:60-61
Server-Side Processing
When an administrator uploads a PWA icon, the server processes the file using the sharp library. The processPwaIconFile function resizes the image to the required dimensions (192 or 512), applies a transparent background for "contain" fitment, and converts the output to a high-quality PNG (92% quality).
Installation Workflow
The installation UI is managed by the usePwaInstall hook, which abstracts the complexity of the browser's beforeinstallprompt event and platform-specific requirements (e.g., iOS vs. Android/Chrome).
Multi-Platform Logic
The installation experience differs significantly based on the user's operating system:
- iOS/Safari: Since iOS does not support the native
beforeinstallprompt, the app displays a specific instructions dialog (PwaInstallDialog) guiding users through the "Add to Home Screen" sharing menu. - Other Platforms: The app listens for the browser's installation event and triggers the native prompt when the user clicks the install button.
UI Components
The installation UI is integrated into multiple areas of the platform:
- Installation Card: A prominent card found on the platform (e.g., sidebar or home) that provides localized descriptions of why the user should install the app.
- User Menu: An "Install app" option within the
HeaderDropdownUserMenuGuest, allowing access to the feature from any page.
Sources: src/components/PwaInstallCard.tsx:50-93, src/app/[locale]/(platform)/_components/HeaderDropdownUserMenuGuest.tsx:142-152
Data Structure and Defaults
PWA settings are stored within the ThemeSiteIdentity interface. The system provides fallback values to ensure a consistent experience even if an administrator hasn't customized the branding.
Identity Interface
The ThemeSiteIdentity includes specific paths and URLs for PWA icons:
pwaIcon192Path: The internal storage path for the 192px icon.pwaIcon512Path: The internal storage path for the 512px icon.pwaIcon192Url: The public-facing URL (defaults to/images/pwa/default-icon-192.png).appleTouchIconUrl: Derived from the 192px icon to provide the correct shortcut icon for Apple devices.
Sources: src/lib/theme-site-identity.ts:60-63, tests/unit/themeSiteIdentity.test.ts:25-27
Summary
The PWA implementation provides a seamless transition from web to mobile home screens. By managing assets through a centralized administrative interface and handling platform-specific installation hurdles (particularly for iOS), the system ensures that the prediction market is accessible as a persistent application. This architecture relies on high-performance image processing on the backend and reactive state management on the frontend to coordinate the installation lifecycle.