Filament Pwa Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require alareqi/filament-pwa
   

   For Filament v4:

   filament-pwa install
   

   For Filament v3:

   filament-pwa install --v3
   

2. Publish Config & Assets

   php artisan vendor:publish --provider="AlaReqi\FilamentPWA\FilamentPWAFacadeServiceProvider" --tag="filament-pwa-config"
   php artisan vendor:publish --provider="AlaReqi\FilamentPWA\FilamentPWAFacadeServiceProvider" --tag="filament-pwa-assets"
   

3. Register Plugin Add to app/Providers/Filament/AdminPanelProvider.php (v3) or bootstrap/app.php (v4):

   // v4
   ->plugin(AlaReqi\FilamentPWA\FilamentPWAPlugin::make())
   

4. First Use Case Visit your Filament admin panel. The PWA prompt will appear automatically after 3 seconds (configurable). Test offline mode by:

   • Disabling network in Chrome DevTools
   • Navigating to Filament - it should load cached assets

Implementation Patterns

Core Workflows

1. Configuration Customization

// config/filament-pwa.php
return [
    'manifest' => [
        'name' => 'My Admin Panel',
        'short_name' => 'Admin',
        'theme_color' => '#2d3748',
        'background_color' => '#ffffff',
        'display' => 'standalone', // 'fullscreen', 'minimal-ui', 'standalone'
        'icons' => [
            [
                'src' => 'icons/icon-72x72.png',
                'sizes' => '72x72',
                'type' => 'image/png',
            ],
            // Add more sizes (192x192, 512x512)
        ],
    ],
    'install_prompt' => [
        'enabled' => true,
        'delay' => 3, // seconds
        'ios_message' => 'Add to Home Screen for quick access',
        'android_message' => 'Install for offline access',
    ],
];

2. Dynamic Icon Generation

Use the generateIcons Artisan command to create icons from a source image:

php artisan filament-pwa:generate-icons --source=public/images/logo.png --output=public/icons

Supports multiple sizes (72x72, 120x120, 144x144, 152x152, 192x192, 384x384, 512x512).

3. Offline Asset Caching

The service worker (filament-pwa-sw.js) automatically caches:

• All Filament assets (CSS, JS, images)
• API routes (configure via cache_strategy)
• Custom routes (add to offline_routes config)

'offline_routes' => [
    'api/admin/resources',
    'api/admin/settings',
],

4. Internationalization

Translate prompts and messages via resources/lang:

// resources/lang/en/pwa.php
return [
    'install_prompt' => [
        'title' => 'Install My Admin',
        'description' => 'Click the install button to use this app offline',
    ],
];

5. Custom Service Worker Logic

Extend the default service worker by publishing the template:

php artisan vendor:publish --provider="AlaReqi\FilamentPWA\FilamentPWAFacadeServiceProvider" --tag="filament-pwa-sw"

Then modify resources/js/filament-pwa-sw.js:

self.addEventListener('install', (event) => {
    event.waitUntil(
        caches.open('filament-pwa-cache').then((cache) => {
            // Custom cache logic
        })
    );
});

Integration Tips

With Filament Resources

• Offline Data Sync: Use the offline_routes config to cache critical API endpoints.
• Example:

  'offline_routes' => [
      'api/admin/resources/{resource}',
      'api/admin/resources/{resource}/{id}',
  ],
  

With Laravel Mix/Vite

• Ensure your build process doesn’t conflict with the PWA service worker registration.
• If using Vite, add this to vite.config.js:

  export default defineConfig({
      build: {
          rollupOptions: {
              output: {
                  manualChunks: (id) => {
                      if (id.includes('node_modules')) {
                          return 'vendor';
                      }
                  },
              },
          },
      },
  });
  

With Filament Notifications

• Show offline status notifications:

  use AlaReqi\FilamentPWA\Facades\FilamentPWA;
  
  FilamentPWA::addNotification(
      title: 'Offline Mode',
      message: 'You are now working offline. Changes will sync when connection is restored.',
      type: 'info'
  );
  

Gotchas and Tips

Common Pitfalls

1. Service Worker Registration Conflicts

• Issue: If you have another PWA library (e.g., Laravel PWA Toolkit), the service worker may fail to register.
• Fix: Disable the conflicting library or merge configurations.

2. Caching Stale Data

• Issue: Offline mode may serve outdated cached data.
• Fix: Use the cache_strategy to control cache behavior:

  'cache_strategy' => 'network-first', // 'cache-first', 'network-only'
  

3. iOS Installation Prompt Limitations

• Issue: iOS ignores beforeinstallprompt events in some contexts.
• Fix: Use the standalone display mode and ensure your manifest is properly configured:

  'manifest' => [
      'display' => 'standalone',
      'apple' => [
          'status_bar_style' => 'black-translucent',
      ],
  ],
  

4. HTTPS Requirement

• Issue: PWAs require HTTPS in production. Local development may fail if not using localhost.
• Fix: Use http://localhost for testing or configure your dev environment with HTTPS.

5. Asset Versioning

• Issue: Cached assets may not update if filenames aren’t versioned.
• Fix: Ensure Laravel’s asset versioning is enabled:

  // config/app.php
  'assets_version' => 'v1.0',
  

Debugging Tips

Service Worker Debugging

1. Open Chrome DevTools (F12).
2. Go to the Application tab → Service Workers.
3. Check the Network tab for filament-pwa-sw.js registration.
4. Use the Application Cache tab to inspect cached assets.

Offline Mode Testing

• Enable Offline Mode in Chrome DevTools (Application → Service Workers → Offline).
• Or use the Application tab → Service Workers → Update on reload.

Manifest Validation

• Validate your manifest at Web Fundamentals Manifest Validator.
• Common errors:
  • Missing start_url.
  • Incorrect icon sizes.
  • Invalid display mode.

Extension Points

Custom Events

Listen for PWA events in your JavaScript:

document.addEventListener('filament-pwa:installed', (event) => {
    console.log('PWA installed!', event.detail);
});

document.addEventListener('filament-pwa:offline', () => {
    // Show offline notification
});

API for Programmatic Control

Use the Facade to trigger actions:

use AlaReqi\FilamentPWA\Facades\FilamentPWA;

// Check if PWA is installed
if (FilamentPWA::isInstalled()) {
    // ...
}

// Show install prompt manually
FilamentPWA::showInstallPrompt();

Custom SW Registration

Override the default service worker registration:

// resources/js/filament-pwa.js
window.addEventListener('load', () => {
    if ('serviceWorker' in navigator) {
        navigator.serviceWorker.register('/custom-sw.js')
            .then((registration) => {
                console.log('Custom SW registered:', registration);
            })
            .catch((error) => {
                console.error('SW registration failed:', error);
            });
    }
});

Dynamic Config Loading

Load PWA config dynamically based on user roles:

FilamentPWA::configure(function ($config) {
    if (auth()->user()->is_admin) {
        $config->manifest['display'] = 'fullscreen';
    }
});