Progressive Web App support for Laravel 12+. Serves a web app manifest and a generated service worker, ships an offline page, and adds Web Push notifications (VAPID), background sync, icon generation and an admin settings screen.
- PHP 8.4+
- Laravel 12 or 13
ext-gd(icon generation)minishlink/web-push^9.0 — only if you use push notifications
The package is not on Packagist yet. Add the repository, then require it:
"repositories": [
{ "type": "vcs", "url": "https://github.com/LaravelPlus/pwa" }
]composer require laravelplus/pwa:dev-masterOr keep it as a git submodule and a composer path repository (packages/laravelplus/pwa).
Run the installer — it publishes the config and the offline page:
php artisan pwa:install # config + assets
php artisan pwa:install --migrations # also publish migrations (push subscriptions)
php artisan migrateAdd the directives to your root layout:
<head>
@pwaHead {{-- manifest link, theme-color, icons --}}
</head>
<body>
...
@pwaScripts {{-- registers /sw.js --}}
</body>Both render nothing when pwa.enabled is false.
Generate icons from a square source PNG (default public/icon.png, written to public/icons):
php artisan pwa:generate-icons --source=public/icon.png| Method | URI | Purpose |
|---|---|---|
| GET | /manifest.webmanifest |
Web app manifest built from pwa.manifest |
| GET | /sw.js |
Service worker |
| GET | /offline |
Offline fallback page |
| POST | /api/pwa/push/subscribe |
Store a push subscription (auth) |
| POST | /api/pwa/push/unsubscribe |
Remove a push subscription (auth) |
| POST | /api/pwa/sync |
Background-sync retry endpoint (auth) |
| GET/PATCH | /admin/pwa |
Admin settings (configurable prefix + middleware) |
config/pwa.php (publish with --tag=pwa-config):
manifest— name, colours, display mode, scope, icons, shortcuts.service_worker—cache_version, Vite asset precaching,offline_page, per-pathcache_strategies(CacheFirst,NetworkFirst, …) andexclude_patterns(Horizon, Telescope and/admin/*by default).push— enable flag and VAPID keys (VAPID_SUBJECT,VAPID_PUBLIC_KEY,VAPID_PRIVATE_KEY).background_sync— enable flag and retry endpoint.icons— source image, output directory, sizes.admin— enable flag, route prefix (admin/pwa) and middleware.
Set pwa.enabled to false to disable routes and directives entirely.
composer require minishlink/web-push
php artisan pwa:vapid # generates VAPID keys and writes them to .envSend through the PwaChannel from any notification by adding toPwa():
use LaravelPlus\Pwa\Notifications\PwaChannel;
public function via(object $notifiable): array
{
return [PwaChannel::class];
}
public function toPwa(object $notifiable): array
{
return [
'title' => 'Order shipped',
'body' => 'Your order is on its way.',
'url' => '/orders/42', // optional
'icon' => '/icons/icon-192x192.png', // optional
];
}| Command | Description |
|---|---|
pwa:install |
Publish config and assets (--migrations, --skills) |
pwa:generate-sw |
Write the service worker to public/sw.js |
pwa:generate-icons |
Generate the icon set from a source PNG (--source, --output) |
pwa:vapid |
Generate VAPID keys and write them to .env |
pwa:clear-cache |
Bump the cache version so clients drop old caches |
| Tag | Contents |
|---|---|
pwa-config |
config/pwa.php |
pwa-migrations |
Push subscription migration |
pwa-assets |
public/offline.html |
pwa-skills / pwa-skills-github |
Claude Code skill for working with the package |
The tests run inside a host Laravel app:
vendor/bin/pest packages/laravelplus/pwa/testsMIT