Filament Pwa Laravel Package

Getting Started

Minimal Steps to Enable PWA in Filament

1. Install the Package

   composer require tomatophh/filament-pwa
   

2. Publish and Run Migrations

   php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsServiceProvider" --tag="migrations"
   php artisan migrate
   php artisan filament-settings-hub:install
   php artisan filament-pwa:install
   

3. Register the Plugin Add the plugin to your AdminPanelProvider in app/Providers/Filament/AdminPanelProvider.php:

   return AdminPanel::make()
       ->plugin(\TomatoPHP\FilamentPWA\FilamentPWAPlugin::make());
   

4. Access the PWA Settings Navigate to Filament Settings Hub → PWA Settings to configure:

   • App name, icons, colors, and offline capabilities.
   • Enable/disable the PWA feature.

5. Test the PWA

   • Open your Filament app in Chrome/Firefox.
   • Check the "Add to Home Screen" prompt or manually install via DevTools (Application > Service Workers).

First Use Case: Quick PWA Setup for Admin Panel

• Goal: Enable offline access for Filament admins.
• Steps:
  1. Configure basic PWA settings (name, icons, theme colors).
  2. Test offline mode by disabling network in DevTools (Application > Service Workers > Offline).
  3. Verify cached assets load when offline.

Implementation Patterns

Workflow: Integrating PWA with Filament

1. Configuration via Filament UI

   • Use the Settings Hub to manage PWA settings without touching code:
     • Upload app icons (192x192, 512x512).
     • Set theme colors (primary, background, text).
     • Enable/disable features like splash screens or push notifications.

2. Dynamic Asset Handling

   • The package auto-generates a manifest.json and sw.js (Service Worker) based on settings.
   • Customization: Override the default Service Worker by publishing the package’s assets:

     php artisan vendor:publish --provider="TomatoPHP\FilamentPWA\FilamentPWAServiceProvider" --tag="pwa-assets"
     

     Then modify /resources/pwa/sw.js or /resources/pwa/manifest.json.

3. Conditional PWA Activation

   • Disable PWA for specific users/roles by extending the plugin:

     FilamentPWAPlugin::make()
         ->canAccess(function (User $user) {
             return $user->isAdmin(); // Example: Only admins get PWA
         })
     

4. Asset Caching Strategy

   • Leverage Filament’s built-in asset versioning to ensure Service Worker caches are updated:

     FilamentPWAPlugin::make()
         ->cacheStrategy('stale-while-revalidate') // Options: 'cache-first', 'network-first'
     

5. Localization Support

   • Use Filament’s localization features to translate PWA prompts:

     FilamentPWAPlugin::make()
         ->translationPrefix('pwa.')
     

     Then add translations to resources/lang/{locale}/pwa.php.

Integration Tips

• Filament Panels: Register the plugin in both AdminPanel and TenantPanel if using multi-tenancy.
• Vite/Laravel Mix: Ensure your build tooling doesn’t conflict with PWA assets. Exclude PWA files from version hashing if needed.
• HTTPS Requirement: PWAs require HTTPS. Use Laravel’s APP_URL with https:// in production.
• Service Worker Debugging: Use the Lighthouse CI to audit PWA compliance:

  npm install -g lighthouse-ci
  lighthouse https://your-filament-app.test --chrome-flags="--headless" --output=html --output-path=./lighthouse-report.html
  

Gotchas and Tips

Pitfalls

1. Service Worker Registration Conflicts

   • Issue: If your app already registers a Service Worker (e.g., via Laravel Mix), the PWA plugin may fail silently.
   • Fix: Disable the default Service Worker in the plugin:

     FilamentPWAPlugin::make()
         ->registerServiceWorker(false)
     

     Then manually register your own SW in resources/js/app.js:

     if ('serviceWorker' in navigator) {
         navigator.serviceWorker.register('/pwa/sw.js');
     }
     

2. Caching Stale Assets

   • Issue: Changes to PWA settings (e.g., icons) may not reflect immediately due to aggressive caching.
   • Fix: Use the filament-pwa:clear-cache command to force a cache refresh:

     php artisan filament-pwa:clear-cache
     

     Or manually update the Service Worker version in manifest.json:

     {
         "name": "My Filament App",
         "short_name": "Filament",
         "version": "1.0.1" // Increment this to bust cache
     }
     

3. Manifest.json Validation

   • Issue: Invalid manifest.json (e.g., missing start_url) can break PWA installation.
   • Fix: Validate your manifest using Web App Manifest Validator.
   • Debugging: Check browser console for errors like:

     Manifest: Line: 1, column: 1, Syntax error.
     

4. Filament Livewire Conflicts

   • Issue: Livewire’s Turbo Drive may interfere with PWA navigation.
   • Fix: Exclude Livewire pages from PWA caching by filtering routes:

     FilamentPWAPlugin::make()
         ->excludeRoutes(['livewire/*', 'filament/pages/*'])
     

Debugging Tips

1. Service Worker Debugging

   • Open DevTools (Application > Service Workers) and check:
     • Registration: Is the SW registered?
     • Events: Listen for install, activate, and fetch events in the SW console.
   • Use workbox-recipes for advanced caching logic:

     // In /resources/pwa/sw.js
     import { precacheAndRoute } from 'workbox-precaching';
     precacheAndRoute(self.__WB_MANIFEST);
     

2. Offline Testing

   • Test offline mode by:
     1. Disabling network in DevTools (Application > Service Workers > Offline).
     2. Reloading the page.
     3. Checking the fetch events in the SW console for cached responses.

3. Filament Plugin Logs

   • Enable debug logging for the PWA plugin:

     'logging' => [
         'channels' => [
             'filament-pwa' => [
                 'driver' => 'single',
                 'path' => storage_path('logs/filament-pwa.log'),
                 'level' => 'debug',
             ],
         ],
     ],
     

     Then add the channel to config/logging.php.

Extension Points

1. Custom PWA Pages

   • Add offline-specific pages (e.g., a "You're offline" view) by extending the plugin:

     FilamentPWAPlugin::make()
         ->offlinePage(function () {
             return view('filament.pwa.offline');
         });
     

2. Dynamic Manifest Data

   • Fetch dynamic data (e.g., user-specific icons) in the Service Worker:

     // In sw.js
     self.addEventListener('install', (event) => {
         event.waitUntil(
             caches.open('dynamic-cache').then((cache) => {
                 return fetch('/api/pwa/dynamic-manifest').then((response) => {
                     return cache.put('dynamic-manifest', response);
                 });
             })
         );
     });
     

3. Push Notifications

   • Integrate push notifications using the Web Push PHP library:

     // In a Filament resource/action
     use WebPush\WebPush;
     
     $subscription = $request->input('subscription');
     WebPush::setVapidCredentials(
         env('VAPID_PUBLIC_KEY'),
         env('VAPID_PRIVATE_KEY'),
         env('VAPID_SUBJECT')
     );
     WebPush::sendNotification($subscription, json_encode(['title' => 'Alert']));
     

   • Configure the plugin to handle subscription storage:

     FilamentPWAPlugin::make()
         ->usePushNotifications()
         ->subscriptionModel(\App\Models\PushSubscription::class);
     

4. Theming

   • Override the default PWA theme by publishing assets and extending the CSS:

     php artisan vendor:publish --provider="TomatoPHP\FilamentPWA\FilamentPWAServiceProvider" --tag="pwa-