Filament Pwa Laravel Package

Product Decisions This Supports

• Defining what "PWA" means for the admin panel — before it lands in a roadmap. The name promises a Progressive Web App; the delivery is <head> metadata (manifest link, theme-color, Apple touch icons, Windows tiles) delegated to laravel-pwa-favicon and laravel-favicon. It ships no service worker, no offline caching, no push, no background sync, no install-prompt handling. The single most consequential decision this package informs is whether the goal is branded home-screen install (in scope) or offline-capable field tooling (not in scope). Getting this wrong in a roadmap doc creates a commitment the package cannot honor.
• Prioritizing by user segment. If mobile field, ops, or on-call staff use the Filament panel, a branded icon and app-like launch are genuine ergonomic and retention wins worth a sprint slot. If the panel is desktop-first for internal analysts, this is cosmetic and belongs low in the backlog.
• A build-vs-buy-vs-copy call, made explicitly. The real output is roughly fifteen lines of static markup, delivered through a three-package, single-maintainer chain. The genuinely reusable value is icon/manifest generation from one source asset plus a maintained config surface. Frame it honestly: "is a one-day in-house render-hook prototype cheaper than owning a low-adoption transitive dependency?"
• Dependency governance as a policy decision. Four stars, zero dependents, one maintainer across the whole chain, MIT licensed, and a future-dated release that should be treated as a data-quality flag until verified. Underwrite this as an approved-dependency question — version pinning, committed lockfile, fork readiness — not a technical debate. Small surface and permissive license keep exit cost near zero.
• Reversibility as a legitimate decision input. No data model, no migrations, no API surface of its own. Rollback is deleting one plugin registration. That low switching cost justifies a timeboxed spike instead of deliberation.
• Deliberate omission as a stated security posture. A service worker caching authenticated Filament HTML is a real staleness and data-exposure hazard. The absence of one is defensible and should be written into the decision record as an intentional product boundary, not read later as an incomplete delivery.
• Stakeholder perception and demo value. Correct app icons, themed browser chrome, and a working "Add to Home Screen" flow are cheap, visible wins for internal demos and exec updates — particularly where a native app budget is not justifiable. This is a communications decision as much as a technical one.

When to Consider This Package

Adopt when:

• Your Filament, Laravel, and PHP versions sit inside the tested support matrix, and you can pin exact versions of all three packages with a committed lockfile.
• A named mobile user group accesses the admin panel, making installability a real ergonomic gain rather than a checkbox.
• You want fast, low-effort panel branding — favicons, Apple touch icons, theme-color, manifest — without hand-rolling icon generation.
• You have a dependency review process that can track upstream releases and schedule compatibility reviews.
• Your CSP is relaxed enough, or you are prepared to audit for nonces/hashes, that manifest and icon fetches will not be silently blocked.
• You accept the boundary that "PWA" here means install and branding, not offline capability.

Look elsewhere or build in-house when:

• You need offline behavior, caching strategies, push, or background sync. This package does nothing there; use a full service-worker solution or build it.
• You need per-tenant, per-panel, or runtime-dynamic manifests and theming. A static head-tag injector likely will not cover multi-tenant branding, and the highest-severity failure mode is one tenant seeing another tenant's icon.
• Your policy bars low-adoption, single-maintainer dependencies in production. Inlining the tag block via PanelsRenderHook::HEAD_END plus a Blade partial is roughly thirty lines and removes the chain entirely.
• Your design system or brand pipeline already owns icon and manifest assets, which makes this duplicative.
• You require an SLA, security response commitments, or commercial support — none exist.
• Accessibility-audited markup is mandatory; audit the emitted tags before shipping.

Spike exit criteria: adopt only if the rendered <head> is clean, Filament major support is confirmed for your version (v3 passing is not evidence for v4), per-panel config demonstrably works, and an in-house prototype does not reach parity within a day. If any of those fail, decline — the dependency buys too little to justify the chain.

How to Pitch It (Stakeholders)

For executives: a small, MIT-licensed add-on that makes our existing Filament admin panel behave like an installable app on phones and tablets — proper home-screen icon, splash assets, themed browser bar, and a web app manifest — without building native apps or paying app-store overhead. Effort is measured in hours, cost is zero, and it is fully reversible: removing it is a one-line change with no data implications. Say the boundary in the same breath: it improves branding and install ergonomics; it does not make the panel work offline and adds no push notifications or background sync. That framing prevents the most likely expectation failure downstream, and it is worth noting the restraint is deliberate — caching authenticated admin HTML in a service worker would be a data-exposure risk we do not want.

For engineering: a thin Filament panel plugin that injects PWA head markup through Filament's render hooks, delegating icon and manifest generation to laravel-pwa-favicon (which pulls jeffersongoncalves/laravel-favicon). No new API surface, no database changes, no middleware, no auth changes, no frontend toolchain impact — install is composer, plugin registration, published config, and an icon set. Flag the real risks: a three-package single-maintainer chain; release 2.1.0 was only a dependency bump, so any upstream break blocks us; strict CSP headers surface as console errors rather than visible failures. Recommend a timeboxed spike on one non-production panel that (1) asserts raw <head> output via an HTTP response test rather than a browser glance, (2) validates install prompts on Android Chrome and iOS Safari, (3) checks CSP, manifest MIME type, dark-mode theme-color, and whether custom login and error pages receive the tags, and (4) pre-agrees the fallback — inline the tag block in a render hook and drop the dependency. Roll out panel by panel so rollback is deleting one registration.