Pwa For Filament Laravel Package

Getting Started

• Install with composer require the package and register the plugin on each panel you want it active for, in the panel provider (->plugin(OfflinePagePlugin::make())). No extra route or middleware wiring should be needed for the default case.
• Look first at (1) your panel provider's colors(), font() and darkMode() calls — as of v0.1.2 the offline page is a direct projection of these; (2) the package config if it exposes route/path or cache settings; (3) the published Blade view if you need to change copy or markup.
• First use case: brand the offline fallback. Set ->colors(['primary' => ..., 'gray' => ...]) and ->font('Inter') on the panel, load a page, then toggle DevTools → Network → Offline and reload. The offline page should render with the same background, surface, text, ring and retry button color as the panel, in both light and dark mode, without writing any CSS.
• If you support multiple panels (e.g. app and admin), you get per-panel offline pages for free after v0.1.2 — each derives from that panel's own theme rather than a shared hardcoded style.

Implementation Patterns

• Theme-driven, not CSS-driven. Treat the offline page as a consumer of the panel theme. Configure primary, gray and font once in the panel provider; resist adding a stylesheet for the offline view. This keeps the page correct when the theme changes later.
• Dark-mode parity. Verify three panel configurations explicitly, because they take three different code paths:
  • ->darkMode(false) → offline page must stay light regardless of OS preference.
  • ->darkMode('forced') (or boolean true if your Filament version uses that form) → offline page must stay dark.
  • Default / user-controlled → the page reads localStorage.theme, mirroring Filament's own bootstrap, and falls back to prefers-color-scheme when the key is absent.
• Custom gray scales. If you register a custom gray palette, do it as a full 50–950 scale. The offline page pulls background, surface, text and ring from it, so partial scales produce gaps or fall through to defaults in one mode only.
• Fonts. Self-host the panel font and ensure the font files are cached by the service worker alongside the offline document. A CDN-loaded font (Bunny/Google) will not resolve while offline, so the page silently falls back to a system stack — the one visual property that won't match until you self-host.
• Copy and structure. Publish the view and edit the heading, body text and retry button label there. Keep the class/attribute hooks the package uses for colors and fonts intact so future releases continue to theme it correctly.
• Retry behaviour. Wire the retry button to a location.reload()-style handler if the published view doesn't already do so; a reload while the network is still down will simply re-render the offline page, which is the expected UX.
• Testing workflow. Add a manual QA step to your release checklist: hard reload with cache cleared, then DevTools offline, in light mode, dark mode, and with localStorage.theme set to the opposite of the OS preference.

Gotchas and Tips

• Upgrade hazard from ≤ v0.1.1. Earlier versions shipped hardcoded zinc styles. Grep your app and any custom CSS for selectors or overrides targeting those offline-page zinc classes — they will silently stop matching after v0.1.2 and leave you with dead overrides or unstyled edge cases.
• Stale service worker cache. The offline document is precached. Theme changes made in the panel provider will not appear until the old asset is invalidated. During development use "Update on reload" / "Bypass for network" in the Application panel; in production rely on the package's cache versioning and bump it if you self-manage the service worker.
• Don't invent a second theme key. The page reads localStorage.theme specifically to stay in sync with Filament's bootstrap. If a custom theme-toggle script writes to a different key or sets data-theme attributes only, the offline page and the app will disagree on dark mode.
• Contrast regressions are easy. Because ring, surface and text all come from gray, a custom palette that is low-contrast in the 700–900 range will make the retry button's ring or the body text nearly invisible in dark mode. Check both extremes of your palette, not just the mid tones.
• Forced dark mode leaks into previews. If you use darkMode('forced') on one panel and default on another, screenshot tests and any shared layout assumptions may diverge; test each panel in isolation rather than assuming the app's default.
• Debugging path. If the offline page looks unstyled or default-browser-ish, first confirm the service worker actually served the package's document (Application → Service Workers → see the fallback URL), then confirm the panel is registered as a plugin on that panel, then check whether a published view got stale.
• Extension point discipline. Overriding more than the view (e.g. republishing CSS) couples you to internals that changed materially in v0.1.2. Prefer the theme configuration surface; if you must override, pin the package version and re-check on each release.