jeffersongoncalves/filament-pwa
Filament PWA adds Progressive Web App support to Filament panels, making admin apps installable and more app-like with a web app manifest, service worker integration, and customizable PWA settings for Laravel projects.
What you are actually installing. Before running composer, internalize the scope: this package injects <head> markup — manifest link, theme-color, Apple touch icons, msapplication-* tiles, favicons — into a Filament panel via render hooks. It does not ship a service worker, offline caching, push notifications, or install-prompt handling. Plan your first use case as branding plus home-screen install, not offline admin.
Steps (≈1–2 hours, most of it icon assets):
composer require jeffersongoncalves/filament-pwa
composer.lock. This pulls laravel-pwa-favicon → jeffersongoncalves/laravel-favicon; you own all three.// app/Providers/Filament/AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
return $panel
->default()
->id('admin')
->path('admin')
// ...
->plugin(\JeffersonGoncalves\FilamentPwa\FilamentPwaPlugin::make());
}
make()/->config() signature from the package README before committing — the docs here describe behavior, not the class name.config/, never vendor:
php artisan vendor:publish --provider="JeffersonGoncalves\FilamentPwa\FilamentPwaServiceProvider"
purpose: "any maskable"), an opaque 180×180 apple-touch-icon, and a favicon .ico/.svg. Put them under public/ with a versioned path (e.g. public/pwa/v1/icon-192.png) so you can cache-bust later.curl -s https://staging.example.com/admin | grep -Ei 'manifest|theme-color|apple-touch-icon|msapplication'
First use case to target: a named mobile/on-call user group installing the panel to a home screen with correct branding. Do not announce "offline admin" — you cannot deliver it.
Config-first, code-second. The published config is the primary integration surface. Treat it as application config (checked into git, environment-aware via env()), and keep the plugin registration itself trivial. Resist the urge to subclass the plugin; there is essentially no seam worth extending.
Panel-by-panel rollout. Register the plugin in AdminPanelProvider only. Leave other panels (/ops, /billing, tenant panels) untouched until the first one has been verified in production for a full release cycle. Because there is no migration or data model, rollback is literally deleting one line — preserve that property by not wiring the plugin into a shared base provider.
Test the head, not the browser. Add an HTTP-level test so regressions surface in CI:
it('emits pwa head tags on the admin panel', function () {
$this->actingAs(User::factory()->create())
->get('/admin')
->assertOk()
->assertSee('rel="manifest"', false)
->assertSee('name="theme-color"', false)
->assertSee('rel="apple-touch-icon"', false);
});
This catches the failure modes that a visual glance misses: tags silently dropped, another plugin overwriting them, or the panel layout changing in a Filament upgrade.
Use render hooks as your override layer. Filament's PanelsRenderHook::HEAD_END is the same seam the package uses. When you need something the config doesn't expose — a dark-mode theme-color variant, a per-route noindex meta, a manifest link for a second domain — append it yourself rather than forking:
use Filament\Support\Facades\FilamentView;
use Filament\View\PanelsRenderHook;
FilamentView::registerRenderHook(
PanelsRenderHook::HEAD_END,
fn () => view('partials.pwa-extra'),
);
Keep the build-vs-buy prototype in your back pocket. The parity implementation is roughly thirty lines: a Blade partial holding the manifest link, theme-color metas, and icon tags, registered on HEAD_END. Run that prototype in parallel during your spike. If it reaches parity within a day — including per-panel config and dark mode — ship the prototype and drop the three-package chain. This is the single highest-leverage decision in the whole evaluation, and it is cheap to make correctly.
Cache-bust the manifest and icons deliberately. Put version numbers in the icon filenames and the manifest URL (/pwa/v1/manifest.webmanifest) rather than relying on query strings — some platforms and CDNs handle query-string caching inconsistently for manifests. If you're behind a CDN that caches HTML, remember the <head> is now part of the cached payload; you'll need a purge on release.
The name oversells the delivery. "PWA" here means installable-with-branding, not offline. Chrome's install criteria have loosened over time, but install UI still varies by browser and platform, and iOS Safari is its own ecosystem. Test the actual install flow on Android Chrome and iOS Safari; don't infer from DevTools' green checkmarks. Write the boundary into the ticket title so it isn't later read as an incomplete delivery.
A service worker caching authenticated Filament HTML would be a security hazard. Stale authenticated pages served from cache after logout is a real data-exposure path. The absence of one is defensible — state it as a deliberate decision in your architecture notes, or someone will "helpfully" add one later.
CSP failures are invisible. A strict Content-Security-Policy on the admin panel will block the manifest fetch via manifest-src (or default-src fallback) and the icons via img-src — and it fails as console-only errors with no visible breakage. Add manifest-src 'self' and ensure img-src allows your icon path. Check the console on every panel you roll out to.
Check for duplicate injectors. If another plugin, your theme, or a legacy Blade layout already emits theme-color or a manifest link, you get last-writer-wins output that is confusing and hard to diagnose — browsers pick one, usually not the one you expect. Grep your rendered HTML for duplicates before assuming the package misconfigured itself.
Head coverage is panel-layout-scoped. Render hooks fire inside the panel layout. Custom login pages, Filament's error pages, and any non-panel routes will not receive the tags. If your login page is a branded custom view, add the tags there by hand.
Multi-tenant and multi-domain branding is not solved. A manifest is a static file at a static URL. If different tenants or different panel domains need different names/icons, a single package config won't get you there — you need a dynamic manifest route keyed per tenant, served with the correct Content-Type: application/manifest+json, and that is outside this package's surface. The worst failure mode here is one tenant seeing another tenant's icon: verify isolation explicitly if you attempt it.
Dark mode theme-color is worth auditing. Filament's dark theme needs a media="(prefers-color-scheme: dark)" variant of the theme-color meta to avoid a jarring light-colored browser bar in dark mode. Inspect the emitted markup; if it's missing, add it via HEAD_END rather than waiting on upstream.
Transitive dependency lag is your problem, not theirs. Release 2.1.0 was a pure dependency bump — meaning a breaking change in laravel-favicon blocks this package until the single maintainer catches up. You cannot patch that locally without forking. Pin exact versions of all three packages, commit the lockfile, and pre-agree the exit: inline the tag block in a render hook and delete the plugin registration. Nobody has to approve a rollback plan that's already written.
iOS icon specifics. apple-touch-icon must be opaque — iOS composites transparency onto black, which looks broken. Supply 180×180 at minimum. Also confirm your start_url and scope in the manifest actually resolve behind your panel path (/admin), or the installed app opens to a 404.
Debug checklist when it "doesn't work":
php artisan config:clear after editing the published config — and remember config:cache in production will freeze it.curl the panel and confirm the tags are in the raw HTML before blaming the browser or the service worker you don't have.localhost is the only exception.How can I help you explore Laravel packages today?