Laravel Pwa Laravel Package

Technical Evaluation

Scope of change under review: foxws/laravel-pwa 2.6.0 — a single additive change (a Laravel Boost skill/tip, PR #22). No runtime code path is implied, semver is respected, and regression risk from the delta is effectively zero. The evaluation below therefore covers adopting the package as a whole; 2.6.0 is noted only where the Boost skill changes how our team would work.

Product value. This package sells a bounded, well-understood outcome: make a Laravel app installable and give it a survivable offline fallback without standing up a Workbox build pipeline. The relevant scope for a TPM is deliberately narrow — manifest generation, service worker registration, Blade head/body directives, and a generated sw.js with a documented caching posture. It is not an offline-data platform, not a sync engine, and not a replacement for a real frontend build. Framing it that way keeps expectations and the business case honest.

Architecture fit.

• Strong fit: Laravel Blade or Livewire apps with a Vite build, served HTTPS-only, whose goal is "install to home screen" plus a graceful offline page.
• Acceptable fit: Inertia apps — the package's default service worker explicitly bypasses X-Inertia, X-Livewire, X-Livewire-Navigate and HX-Request requests, which is the single most important correctness detail for avoiding the classic stale-shell failure.
• Poor fit: API-only services, native-client backends, admin panels where offline caching is a compliance or security liability, or any app already owning a Workbox service worker at the same scope.

Integration feasibility. Low ceremony and no infrastructure dependency: composer require, vendor:publish --tag="pwa-config", @pwaHead in <head>, @pwaSw before </body>, then php artisan pwa:generate. Cost is dominated by things that are not PHP: producing icon assets (192/512 PNG + apple-touch-icon), running storage:link, authoring an offline.html (the package does not ship the offline page in the generated flow — it must be created), and adding pwa:generate to the deploy pipeline. Those are the line items that turn a one-hour install into a one-week rollout if left unplanned.

Technical risk. Concentrated in browser-contract and release-process concerns, not in the package's PHP:

Key questions to close before committing engineering time.

1. What is the supported Laravel/PHP matrix, and is it CI-covered? Cheapest possible disqualifier.
2. Customization source of truth for the service worker: published view template, or the stub that pwa:generate copies into public/sw.js? If the latter, how do we persist custom logic across deploys without patching the package?
3. Does the fetch handler hard-skip all non-GET methods, or only route around them via headers/paths?
4. Exact interaction of pwa:generate with config:cache — does it read the live config or the cached config at build time?
5. Subdirectory and multi-domain deployments: how are scope and start_url derived, and can they be overridden cleanly?
6. Is push notification support config-gated, and do we intend to use it? (If yes, VAPID keys, a push handler, and a subscribe flow become in-scope and roughly double the work.) If no, ensure the flag stays off.
7. What does the Boost skill encode, and can we audit it as plain text in the repo before enabling it for the team?
8. Do the generated icons/manifest actually resolve through a proxy (APP_URL + TrustProxies correctness), which is a silent installability failure?

Integration Approach

Stack fit. Target the marketing/marketing-adjacent authenticated shell first: static marketing routes plus a static offline page. Do not attempt offline-capable application data in phase one — the package provides a static fallback, not a write-through data layer, and conflating the two is how these projects turn into multi-month efforts.

Migration path — additive and reversible by design.

1. Spike branch (timeboxed). Install, publish config, wire @pwaHead/@pwaSw into the single base layout, run pwa:generate, validate with DevTools → Application and Lighthouse's installability audit.
2. Deploy-path gate. Ship a trivial change to staging and confirm a real device picks it up without manual cache clearing. This is the go/no-go gate. If invalidation fails here, stop and re-scope rather than discovering it in production.
3. Feature-flag the surface. Wrap the directives so PWA can be enabled per-layout and disabled globally by a config/env flip. Exercise the PWA_ENABLED=false self-unregister path at least once before launch so the rollback is proven, not theorized.
4. Keep the integration thin. One layout include, one config file, one deploy step. Success criterion: removal is a single PR.

Compatibility checks, in cost order.

• Version constraint against our pinned Laravel/PHP — do this before writing any code.
• Existing service worker audit at the intended scope, including anything a CMS or admin tool registered.
• HTTPS in every environment we intend to test. Staging on plain HTTP or testing from a phone over http://192.168.x.x will not reproduce production behavior and will burn a QA cycle on a non-bug.
• storage:link presence and icon assets in the built output — verified against npm run build, not just artisan serve.

Sequencing and rough sizing.

Total: ~5–8 dev-days to production-ready on a single layout, excluding push notifications. Step 9 is strictly last — it is a documentation artifact and must never gate the rollout.

Explicit non-goals for phase one: push notifications, background sync, offline mutation queues, and per-route caching strategies beyond the package defaults. Revisit only after the install flow and stale-deploy behavior have been observed in the wild for a full release cycle.

Operational Impact

Maintenance. Small surface area — config, generated static assets, one Blade include, one artisan command in the deploy script. No schema, no queue, no external service, no secrets (unless push is enabled). Ongoing cost is two things: tracking a low-bus-factor dependency (mitigate by pinning an exact version, reviewing changelogs on bump, and confirming the codebase stays small enough to fork or vendor under MIT) and owning the cache-invalidation policy, which is ours regardless of what the package does. The 2.6.0 change adds no maintenance obligation and no attack surface.

Support. Developers consume it; end users experience the failures. Expect two ticket archetypes: "the site is showing old content" and "the app won't update / won't install." Both are near-undiagnosable without a prepared runbook. The runbook must contain, in this order: config flags → DevTools Application tab (is the SW active?) → Network tab (is the request reaching the network?) → Lighthouse. It must also include the remote kill switch (PWA_ENABLED=false + pwa:generate) with a documented expectation that propagation is not immediate, and end-user "clear site data" instructions for the iOS manual-install path. Budget first-line support enablement, not just engineering time — this is the most commonly under-resourced line item in PWA rollouts.

Scaling. No server-side scaling cost and no new runtime to operate. Static assets and the offline fallback move off the origin for repeat visits, reducing bandwidth and improving perceived performance; that is a real but modest win and should not be the primary justification. The meaningful "scaling" cost is client-state complexity: every added caching strategy or offline behavior multiplies the space of states a bug report can come from. Enforce a rule that new caching rules require a named owner and a test scenario in the QA checklist.

Failure modes and pre-agreed responses.

• Stale shell / "white screen after deploy." Highest-impact mode. Detection: post-deploy smoke test from a device that visited before the deploy. Response: bump the generated artifacts, confirm pwa:generate ran, then advise the kill switch if unresolved.
• Manifest icons 404 → not installable, no error surfaced. Detection: Lighthouse gate in CI on a canary route. Response: verify storage:link and APP_URL/TrustProxies behind the proxy.
• Scope collision with an existing SW. Detection: pre-flight audit. Response: change registration scope rather than fight the other worker.
• Stale auth state served to a logged-in user. Mitigated by network-first for pages and header/path bypass, but must be explicitly tested with a login-then-navigate scenario.
• Deploy skipped pwa:generate. Detection: assert generated artifact freshness in the pipeline. Response: treat as a failed deploy, not a follow-up ticket.
• Rollback not taking effect. The self-unregistering SW needs a browser update check; document the 24h default update_interval as the worst-case propagation window so nobody promises an instant revert.

Ramp-up. Low for any Laravel developer — the whole integration is two Blade directives plus an artisan command. The learning curve is in the browser contract (scope, HTTPS, update lifecycle), not the package. Plan a single 60-minute walkthrough for the team that owns releases, and make the Boost skill the default source of truth for AI-assisted changes so generated code follows the package's conventions (change config → pwa:generate) rather than hand-editing public/sw.js.

Recommendation. Proceed, scoped to installability plus a static offline fallback on the marketing routes, with the deploy-path gate in step 2 as a hard go/no-go and the rollback path exercised before launch. Hold push notifications and any offline data strategy out of scope. Pin the dependency exactly, keep the integration to a single PR's worth of removal, and treat the Boost skill as an additive documentation artifact adopted at the end.