nyoncode/laravel-pwa
| Install | |
|---|---|
composer require nyoncode/laravel-pwa |
|
| Latest Version: | v1.0.1 |
| PHP: | ^8.2 |
| Laravel: | 12 · 13 |
| License: | MIT |
| Last Updated: | Nov 21, 2026 |
| Links: | GitHub · Packagist |
Laravel PWA
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 · Live demo · Čeština · Changelog · Upgrade guide
| Update toast | Offline: cached page | Offline: never opened | iPhone install |
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
Screenshots from the live demo, a static copy of an app with the package installed.
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:push:prune |
Deletes expired and long-unused push subscriptions (schedule it daily) |
pwa:doctor |
Checks HTTPS, icons, build, cache rules, maintenance exceptions, session |
Documentation
The documentation is also available in Czech.
Support policy
| Version | PHP | Laravel | Status |
|---|---|---|---|
| 1.x | 8.2 – 8.5 | 12, 13 | Active |
The package follows Semantic Versioning: minor releases never break the public API. 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.
Related Packages
A comprehensive PWA (Progressive Web App) plugin for Filament v3 and v4 admin pa...
Comprehensive PWA integration for Laravel 13 + Vite 7 with Inertia v3 support
Zero-config browser push notifications for Filament. Piggybacks on database noti...
In-app notifications for the noerd framework: a bell in the top bar with an unre...
Version History
| Version | Released | PHP | Laravel | License |
|---|---|---|---|---|
| v1.0.1 | ^8.2 | ^12.0| | MIT | |
| v1.0.0 | ^8.2 | ^12.0| | MIT |



