nyoncode / laravel-pwa
Production-grade PWA for Laravel: offline-first service worker with per-user caches and cache rules, persistent login, maintenance screen, kill switch, web push notifications and per-tenant manifests.
Requires
- php: ^8.2
- illuminate/support: ^12.0|^13.0
- nyoncode/laravel-package-toolkit: ^2.5
Requires (Dev)
- driftingly/rector-laravel: ^2.7
- larastan/larastan: ^3.0
- laravel/pint: ^1.24
- minishlink/web-push: ^10.0|^11.0
- nyoncode/laravel-package-console: ^1.0
- orchestra/testbench: ^10.0|^11.0
- pestphp/pest: ^3.8|^4.0
- pestphp/pest-plugin-laravel: ^3.2|^4.0
- rector/rector: ^2.8
Suggests
- ext-gd: Required to generate icons from PNG with pwa:icons
- ext-imagick: Required to generate icons from SVG with pwa:icons
- minishlink/web-push: Required to send web push notifications (pwa.push.enabled)
Provides
None
Conflicts
None
Replaces
None
README
A production-grade Progressive Web App for Laravel. Make your app installable, keep it working offline without ever showing one user another user's data, keep installed apps signed in, show a real maintenance screen, and switch the service worker off on every device with one command.
Documentation · Čeština · Changelog · Upgrade guide
Quick start
composer require nyoncode/laravel-pwa php artisan pwa:install php artisan pwa:icons resources/pwa/icon.png
<head> <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover"> <x-pwa::head/> </head>
npm run build && php artisan pwa:build # on every deploy (also runs with php artisan optimize) php artisan pwa:doctor # checks HTTPS, icons, build, maintenance exceptions, session
That is a complete, installable PWA with an offline screen. Everything else is opt-in.
Why this package?
Most PWA packages generate a manifest and a generic service worker. The hard part of a PWA in a real Laravel app is everything around it, and that is what this package is built for:
- The server decides what is cached. No HTML page is stored until a route opts in with the
pwa.cachemiddleware. Authenticated pages never leak into a generic "cache everything" rule. - Caches are per user. Pages, API responses and images are stored per signed-in user and purged on logout or when another user signs in on the same device, including XHR logins (Inertia, Livewire, SPAs).
- Maintenance is not "offline". The worker tells a
503from a network failure, shows your maintenance screen and keeps the cache intact.php artisan pwa:downwrapsartisan down. - Installed apps stay signed in. Remember-me in the installed app, a sliding session and an
automatic CSRF refresh, so users never see a
419. - A kill switch.
php artisan pwa:disableremoves the service worker from every device without a deploy, because a broken worker survives a fixed server. - One app, one URL. Desktop Edge and Chrome get
minimal-uiwith Back and Reload buttons; phones, tablets and Safari getstandalone. No user-agent sniffing. - Push that respects shared devices. Optional web push with a Laravel notification channel: logout removes the device's subscription, and a device where someone else is signed in shows a neutral notification instead of the content.
Features
| Area | What you get | Docs |
|---|---|---|
| Manifest | /manifest.webmanifest from config and a fluent API, display modes, icons, shortcuts |
Manifest, Display modes |
| Icons and splash | pwa:icons: any, maskable, monochrome and iOS icons, iOS splash screens for every iPhone and iPad |
Commands |
| Dynamic manifest | Per-request resolvers for tenants, branding and locales; Octane-safe | Manifest |
| Service worker | Built from your Vite manifest, versioned, auto-updating | Service worker |
| Cache rules | network-first, cache-first, stale-while-revalidate, network-only, cache-only; per user or shared; limits and expiry | Cache rules |
| Offline | Offline screen, offline pages with server consent, warm-up of unvisited pages, offline queue for forms and API calls | Offline |
| Push notifications | Optional: WebPushChannel, Pwa.push.subscribe(), VAPID keys, per-device subscriptions, Declarative Web Push, WebPush::fake() |
Push notifications |
| Multi-tenant | One installable app per path tenant (/t/acme/): own worker scope, manifest identity and caches |
Multi-tenant apps |
| Session | Persistent login in the installed app, keep-alive, CSRF refresh | Persistent login |
| Maintenance | Maintenance screen, pwa:down, 503 vs. network failure |
Maintenance |
| Kill switch | pwa:disable / pwa:enable |
Kill switch |
| Client | window.Pwa, pwa:* events, Livewire and Inertia adapters |
Client, Adapters |
| Events | ManifestResolving, ServiceWorkerBuilt, kill switch, telemetry and push events |
Events |
| Testing | asInstalledApp(), assertPwaCacheable(), assertValidManifest() and more |
Testing |
| Extensibility | sw.import / sw.extend and self.PwaWorker for your own worker code |
Service worker |
| AI agents | MCP server, agent guide and Claude Code skill, read from your installed version | AI agents |
A taste of the API
// Pages available offline (the server consents per route) Route::get('/dashboard', DashboardController::class)->middleware('pwa.cache'); // Remember-me in the installed app Route::post('/login', LoginController::class)->middleware('pwa.remember'); // Cache rules for API calls, in AppServiceProvider::boot() Pwa::serviceWorker()->cache('/api/catalog*')->staleWhileRevalidate()->maxEntries(200)->maxAge(days: 1); // A manifest per tenant Pwa::manifest()->resolveUsing(fn (Request $request, ManifestBuilder $manifest) => $manifest ->name($request->tenant()->name) ->themeColor($request->tenant()->color));
// In your tests $this->asInstalledApp()->get('/dashboard')->assertPwaCacheable(); $this->get('/manifest.webmanifest')->assertValidManifest();
Commands
| Command | What it does |
|---|---|
pwa:install |
Publishes the config and prints the next steps |
pwa:build / pwa:clear |
Builds / removes the service worker (hooked into optimize) |
pwa:icons {source} |
Generates any, maskable, apple-touch-icon and favicon icons |
pwa:down |
artisan down with the PWA maintenance screen |
pwa:disable / pwa:enable |
Kill switch for the service worker on every device |
pwa:push:vapid |
Generates the VAPID keys for web push |
pwa:doctor |
Checks HTTPS, icons, build, cache rules, maintenance exceptions, session |
Documentation
| Getting started | Features | Integrations | Operations |
|---|---|---|---|
| Overview | Display modes | JavaScript client | Commands |
| Installation | Manifest | Events | Deployment |
| Configuration | Blade components | Multi-tenant apps | Security |
| Service worker | Livewire and Inertia | Platform support | |
| Offline | Push notifications | Troubleshooting | |
| Persistent login | AI agents | Testing | |
| Maintenance | |||
| Kill switch |
The documentation is also available in Czech.
Support policy
| Version | PHP | Laravel | Status |
|---|---|---|---|
| 0.4 | 8.2 – 8.5 | 12, 13 | Active |
| 0.3 | 8.2 – 8.5 | 12, 13 | Security fixes until 0.4.0 + 3 months |
| 0.2 | 8.2 – 8.5 | 12, 13 | Security fixes until 0.3.0 + 3 months |
| 0.1 | 8.2 – 8.5 | 12, 13 | Security fixes until 0.2.0 + 3 months |
Laravel 11 and older are end of life and not supported. Every release is tested against the lowest and the latest dependencies on every supported PHP and Laravel version.
AI agents and MCP
The package ships documentation for coding agents inside vendor/, so an agent reads the version
from your composer.lock, not from its training data:
vendor/bin/pwa-ai install
This adds a block to AGENTS.md, the laravel-pwa Claude Code skill and the laravel-pwa MCP
server to .mcp.json (Node 18+, no dependencies). See AI agents.
Contributing and security
See CONTRIBUTING.md. Please report vulnerabilities privately as described in SECURITY.md, not in public issues.
License
MIT. See LICENSE.md.