Laravel Pwa Laravel Package

Product Decisions This Supports

• Installability as a feature bet, not a rewrite. If the roadmap item is "let users add us to their home screen / launch like an app," this package delivers the manifest, icons, theme-color, service worker registration, and offline fallback through Laravel config, routes, and Blade directives — no separate frontend toolchain, no Workbox build pipeline. That means the decision is scoped to a sprint, not a quarter.
• Build vs. buy for the PWA plumbing layer. The alternative is hand-rolling a manifest route, a service worker stub with cache strategies, and blade meta-tag includes — a few days of engineering plus ongoing browser-contract maintenance. This package makes it a composer require plus a pwa:generate command. Buy, unless you already own a service worker.
• Retention and re-engagement experiments. Install prompts, home-screen presence, and offline tolerance for marketing pages are cheap levers to test on mobile web traffic before committing to native app investment. This is the "validate demand for app-like usage" experiment.
• Scope containment for offline. The realistic first use case is narrow: make the marketing site and a static offline page installable, confirm the Chrome install icon appears on a real device, then stop. Do not let the roadmap expand into offline data sync — that is a separate product decision requiring IndexedDB write-through and is not what this package provides.
• Explicit non-goals to document. Admin panels behind auth (caching is a liability there, not a benefit), API-only services, and anything already shipping a Workbox build. Also: iOS gets no beforeinstallprompt, so onboarding flows must never gate on an install prompt — an install-coaching UX decision, not just an engineering one.
• Reverse-and-recover capability. PWA_ENABLED=false plus pwa:generate writes a self-unregistering service worker that clears caches and removes itself. That gives us a genuine kill switch — a real de-risking factor for a client-side feature that is otherwise hard to roll back.
• Tooling/agent leverage (2.6.0). The Boost skill encodes correct package conventions (directives, pwa:generate, ignore_paths, cache-busting) so AI-assisted changes produce idiomatic output instead of ad-hoc Workbox. Nice-to-have; it should never gate the rollout and is inert for teams not using Boost.

When to Consider This Package

Adopt when:

• Laravel 10/11/12 Blade, Livewire, or Inertia app with a Vite build, served over HTTPS (or localhost). Verify the PHP/Laravel constraint matrix against our pinned versions first — cheapest possible disqualifier.
• The goal is installability plus a graceful static offline fallback, not offline-capable application state.
• No existing service worker at the intended scope. One SW per scope: any prior in-house or CMS-registered worker at or above the registration path will collide.
• We want the PWA surface flaggable per layout/route so it can be enabled incrementally and removed in a single PR.
• Someone owns the cache-invalidation policy as a release-time responsibility. The package gives versioned ?v= manifest/SW URLs from last-modified time, which handles the common stale-deploy case — but the cache-name-as-deployment-artifact discipline still needs a human.

Look elsewhere or build when:

• We need offline data ("last viewed record still readable") — that is application-layer IndexedDB work, not this.
• We need push notifications with real delivery guarantees. Config flags exist, but VAPID keys, a push handler, and a subscribe flow are on us, and misconfiguration fails silently.
• Background sync, complex Workbox routing, or precaching of a large hashed asset graph are requirements.
• API-only service with native clients, or a single-maintainer dependency we'd need on a critical path. One GitHub star and a small maintainer footprint means: pin exactly, keep the integration thin enough to remove in one PR, and treat the published views as the customization surface — the package is scaffolding, not an abstraction to subclass.

How to Pitch It (Stakeholders)

For executives: This is a small, reversible, low-cost bet that makes our Laravel web app installable on phones — home-screen icon, app-like launch, a graceful page instead of a browser error when connectivity drops. It reuses the stack we already have, requires no new infrastructure, no new vendor, and no native app team. We can turn it off with one config flag and a regenerate command, which pushes a self-removing service worker to clients. The honest sizing: it is a few days of engineering plus cross-device QA, and its risk is concentrated in one place — stale content after a deploy — which we mitigate with a versioning scheme the package already provides and a documented release step. Worth doing if installability is on the roadmap; not worth doing as a speculative "we should have a PWA."

For engineering: composer require, publish config, run pwa:generate, drop @pwaHead in <head> and @pwaSw before </body> in the root layout. Those are Blade includes, not components — no <x-pwa-head>. Don't hand-write manifest.json or sw.js; change config/pwa.php and regenerate on every deploy and config change. The service worker is network-first for pages and cache-first for assets, and already bypasses Inertia, Livewire, and htmx requests plus pwa.ignore_paths — keep that list current and make sure auth, CSRF, and any state-changing route bypass the cache. Set APP_URL and TrustProxies correctly or the manifest will reference icons on a different origin and installability fails with no useful error. route:cache and config:cache in the deploy script can freeze manifest/SW config, so clear both as part of release.

Sequencing we ask for: spike in a branch → deliberately test the deploy path (ship a trivial change, confirm clients pick it up without manual cache clear — this is the gate; if it fails, stop) → agree cache-invalidation ownership with the release owner → confirm manifest and icons resolve in the built Vite output, not just artisan serve → cross-device QA (Chromium desktop/Android, iOS Safari) plus one offline and one stale-deploy scenario → canary on a low-traffic route → widen. Adopt the Boost skill last; it's a documentation artifact.

What we owe support: a runbook before launch. Expect "the site is showing old content" and "the app won't update" tickets, which are near-impossible to diagnose ad hoc. Include how to identify a stale-SW client, force a refresh, and unregister remotely. Budget first-line enablement, not just engineering time.