README

Laravel PWA Service Worker

Serve a production-ready PWA service worker at /sw.js, rendered from a Blade template whose cache version tracks the Vite build manifest hash — so a npm run build automatically busts the SW cache without you editing the worker.

Ships three caching strategies out of the box:

• cache-first for content-hashed /build/* assets (immutable, safe to cache forever)
• network-first for HTML navigations (fresh when online, cached + offline fallback when not)
• stale-while-revalidate for everything else (images, fonts, …)

…plus precache on install, old-cache teardown on activate, and a pwa-updated postMessage so your front-end can show an "update available" toast.

Installation

composer require jeffersongoncalves/laravel-pwa-service-worker

The /sw.js route is registered automatically. Register the service worker from your layout:

<script>
  if ('serviceWorker' in navigator) {
    navigator.serviceWorker.register('/sw.js');
  }
</script>

Optionally publish the config and view:

php artisan vendor:publish --tag="pwa-service-worker-config"
php artisan vendor:publish --tag="pwa-service-worker-views"

Update notifications

When a new worker activates it postMessages { type: 'pwa-updated', version } to every controlled page. Listen for it to surface an "update available" prompt and reload once the user accepts:

<script>
  if ('serviceWorker' in navigator) {
    navigator.serviceWorker.register('/sw.js');

    let reloading = false;

    navigator.serviceWorker.addEventListener('message', (event) => {
      if (event.data?.type !== 'pwa-updated') {
        return;
      }

      // First install fires this too; only prompt when a worker was already
      // in control (i.e. this is a genuine upgrade, not the initial load).
      if (!navigator.serviceWorker.controller) {
        return;
      }

      if (window.confirm('A new version is available. Reload now?')) {
        window.location.reload();
      }
    });

    // Guard against reload loops if the SW takes control mid-session.
    navigator.serviceWorker.addEventListener('controllerchange', () => {
      if (reloading) {
        return;
      }
      reloading = true;
    });
  }
</script>

Offline fallback

The worker serves config('pwa-service-worker.offline_url') (default /offline) for a failed navigation when nothing is cached. You register that route — it is intentionally not provided, since the offline page is app-specific:

Route::view('/offline', 'offline')->name('pwa.offline');

Configuration

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.