Pwa Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require laravelir/pwa
   

   Publish the config file:

   php artisan vendor:publish --provider="Laravelir\Pwa\PwaServiceProvider"
   

2. Basic Configuration Edit config/pwa.php to define:

   • manifest (path to your web app manifest)
   • service_worker (path to your service worker script)
   • icons (array of icon paths for different resolutions)
   • theme_color and background_color (for PWA theme consistency)

3. First Use Case: Add PWA Meta Tags Include the PWA service provider in config/app.php:

   'providers' => [
       Laravelir\Pwa\PwaServiceProvider::class,
   ],
   

   Add the PWA tag to your app.blade.php (or layout file):

   @pwa
   

Implementation Patterns

1. Dynamic Manifest Generation

Use Laravel’s blade directives to dynamically set manifest properties:

@pwa([
    'name' => config('app.name'),
    'short_name' => Str::limit(config('app.name'), 12),
    'start_url' => url('/'),
    'display' => 'standalone',
])

2. Conditional PWA Loading

Disable PWA for specific routes or user roles:

// In a middleware or controller
if (auth()->check() && auth()->user()->is_admin) {
    return response()->view('admin.dashboard')->withoutPwa();
}

3. Service Worker Updates

Trigger service worker updates via Laravel events (e.g., after deployment):

// In a command or event listener
event(new \Laravelir\Pwa\Events\ServiceWorkerUpdated);

4. Asset Versioning for Cache Busting

Leverage Laravel Mix/Vite to version assets and update the manifest dynamically:

// mix.js
mix.version();

@pwa([
    'icons' => [
        asset('images/icon-192x192.png?v=' . config('app.version')),
        asset('images/icon-512x512.png?v=' . config('app.version')),
    ],
])

5. Integration with Laravel Mix

Extend your webpack.mix.js to compile PWA assets:

mix.js('resources/js/service-worker.js', 'public/js')
   .postCss('resources/css/pwa.css', 'public/css', [
       require('postcss-import'),
       require('tailwindcss'),
   ]);

Gotchas and Tips

1. Service Worker Registration

• Gotcha: The service worker must be registered in the browser after the page loads. Use a script tag at the end of <body>:

  <script src="{{ asset('js/service-worker.js') }}"></script>
  

• Tip: Test service worker registration with:

  php artisan pwa:test
  

2. Manifest Validation

• Gotcha: Invalid manifest properties (e.g., missing name or icons) will cause PWA installation to fail.
• Tip: Validate your manifest using Google’s PWA Checker or:

  php artisan pwa:validate
  

3. Caching Quirks

• Gotcha: Aggressive caching in the service worker may break updates. Use a versioned cache strategy:

  // In your service-worker.js
  const CACHE_NAME = `cache-v${appVersion}`;
  

• Tip: Clear old caches during updates:

  self.addEventListener('activate', (event) => {
      event.waitUntil(
          caches.keys().then((cacheNames) => {
              return Promise.all(
                  cacheNames.map((cache) => {
                      if (cache !== CACHE_NAME) {
                          return caches.delete(cache);
                      }
                  })
              );
          })
      );
  });
  

4. Offline Fallback Pages

• Tip: Configure a fallback page in your service worker:

  self.addEventListener('fetch', (event) => {
      event.respondWith(
          caches.match(event.request).then((response) => {
              return response || caches.match('/offline');
          })
      );
  });
  

  Create a blade template at resources/views/offline.blade.php.

5. Debugging

• Tip: Use the Application tab in Chrome DevTools to inspect PWA registration and service worker state.
• Gotcha: Service workers run in a separate thread. Use console.log in the worker to debug:

  self.addEventListener('install', (event) => {
      self.clients.matchAll().then((clients) => {
          clients.forEach((client) => {
              client.postMessage('Service worker installed!');
          });
      });
  });
  

6. Extending Functionality

• Tip: Override default behavior by publishing and modifying the service worker template:

  php artisan vendor:publish --tag=pwa-assets
  

  Edit resources/views/vendor/pwa/service-worker.blade.php.

7. Testing

• Tip: Test PWA features in Chrome with:
  • Application tab → Install app
  • Sensors tab → Simulate offline mode
• Gotcha: Some browsers (e.g., Safari) require HTTPS for service workers. Use trust-proxy middleware in development:

  TrustProxies::middlewares(['fideloper/proxy']);