PWA Configuration and Technical Implementation

Overview

This document provides technical documentation for the PWA configuration functionality in the PwaSettings module. It describes the components, configuration options, and implementation details for transforming your Laravel application into a Progressive Web App.

Technical Components

Models

Settings

namespace Modules\PwaSettings\Models;

// Main configuration model for PWA settings
class Settings extends Model
{
    // Core PWA manifest properties
    public $fillable = [
        'pwa_active',           // Enable/disable PWA functionality
        'name',                 // Full application name
        'short_name',           // Short name for home screen
        'scope',                // PWA scope URL
        'start_url',            // Starting URL when launched
        'display',              // Display mode (standalone, fullscreen, etc.)
        'orientation',          // Screen orientation preference
        'description',          // App description
        'background_color',     // Background color
        'theme_color',          // Theme color for browser UI
        
        // Icon configuration
        'android_icons_size',   // Android icon sizes array
        'ios_icons_size',       // iOS icon sizes array
        'maskable_icons_size',  // Maskable icon sizes array
        
        // Advanced features
        'enable_offline_mode',  // Offline functionality
        'cache_strategy',       // Caching strategy enum
        'enable_install_button' // Show install prompt
    ];
}

Services

ManifestService

namespace Modules\PwaSettings\Services;

// Service for generating PWA manifest
class ManifestService
{
    // Generates the complete manifest.json content
    public function generateManifest(): array;
    
    // Generates icons array for manifest
    private function generateIcons(Settings $settings): array;
    
    // Gets default manifest when PWA is not active
    private function getDefaultManifest(): array;
}

ServiceWorkerService

namespace Modules\PwaSettings\Services;

// Service for generating service worker
class ServiceWorkerService
{
    // Generates the service worker JavaScript content using Workbox
    public function generateServiceWorker($settings): string;
    
    // Generates minimal service worker when offline mode is disabled
    private function generateMinimalServiceWorker(): string;
}

Controllers

ManifestController

namespace Modules\Pwasettings\Http\Controllers;

// Controller for serving PWA manifest
class ManifestController extends Controller
{
    // Serves the manifest.json file
    public function manifest(Request $request): JsonResponse;
}

PwaController

namespace Modules\PwaSettings\Http\Controllers;

// Controller for PWA-related endpoints
class PwaController extends Controller
{
    // Serves the service worker script
    public function serviceWorker(Request $request): Response;
}

Configuration Options

Display Modes

Mode	Description	Use Case
standalone	App appears without browser UI	Most common PWA mode
fullscreen	App takes full screen	Games, media apps
minimal-ui	Minimal browser UI shown	Apps needing some browser features

Orientation Options

Orientation	Description
any	No orientation preference
landscape	Landscape mode only
portrait	Portrait mode only

Cache Strategies

Strategy	Description	Best For
CacheFirst	Serve from cache, fallback to network	Static assets, images
NetworkFirst	Try network first, fallback to cache	Dynamic content, API calls
StaleWhileRevalidate	Serve from cache, update in background	Frequently updated content

Manifest Generation Process

1. Settings Retrieval

   • ManifestService retrieves settings from database
   • Uses default values when PWA is not active

2. Icon Processing

   • Processes Android, iOS, and maskable icon configurations
   • Generates icon entries with proper sizes and purposes
   • Uses fallback icon if no icons are configured

3. Manifest Assembly

   • Combines all configuration into valid manifest structure
   • Returns JSON response with proper headers

Icon Management

The module supports three types of icons:

• Android Icons: Stored in android_icons_size array field
• iOS Icons: Stored in ios_icons_size array field
• Maskable Icons: Stored in maskable_icons_size array field

Icon sizes are configurable through the Filament admin interface and stored as JSON arrays in the database.

Meta Tag Generation

The module automatically generates PWA-related meta tags:

Basic PWA Meta Tags

<meta name="application-name" content="{{ $settings->name }}">
<meta name="description" content="{{ $settings->description }}">
<meta name="theme-color" content="{{ $settings->theme_color }}">
<meta name="msapplication-TileColor" content="{{ $settings->background_color }}">

iOS-Specific Meta Tags

<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="{{ $settings->short_name }}">

Social Media Integration

<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="{{ $settings->twitter_og_title }}">
<meta name="twitter:description" content="{{ $settings->twitter_og_description }}">
<meta property="og:title" content="{{ $settings->twitter_og_title }}">
<meta property="og:url" content="{{ $settings->twitter_og_url }}">

Database Schema

pwa_settings

Column	Type	Description
id	bigint	Primary key
pwa_active	boolean	Enable PWA functionality
name	string	Full application name
short_name	string	Short name for home screen
scope	string	PWA scope URL
start_url	string	Starting URL
display	enum	Display mode
orientation	enum	Screen orientation
description	text	App description
background_color	string	Background color hex
theme_color	string	Theme color hex
android_icons_size	json	Android icon sizes array
ios_icons_size	json	iOS icon sizes array
maskable_icons_size	json	Maskable icon sizes array
enable_offline_mode	boolean	Offline functionality
cache_strategy	enum	Caching strategy
cache_pages	boolean	Cache HTML pages
cache_api_requests	boolean	Cache API responses
cache_static_assets	boolean	Cache CSS/JS/images
cache_max_age_seconds	integer	Cache expiration time
max_cache_entries	integer	Maximum cache entries
enable_install_button	boolean	Show install prompt

Integration Points

Filament Integration

The module integrates with Filament through:

• SettingsPage: Comprehensive configuration interface
• PwaSettingsPlugin: Plugin registration and discovery
• Render Hooks: Install button injection

Route Registration

// Automatic route registration in ServiceProvider
Route::prefix('pwa')->name('pwa.')->group(function () {
    Route::get('/manifest.json', [ManifestController::class, 'manifest'])->name('manifest');
    Route::get('/sw.js', [PwaController::class, 'serviceWorker'])->name('sw');
});