Installation
After these steps your app is installable, works offline, and php artisan pwa:doctor reports all green.
Requirements
| What | Version |
|---|---|
| PHP | 8.2+ (Laravel 13 requires 8.3+) |
| Laravel | 12.x or 13.x |
| HTTPS | required in production; localhost is exempt |
| Vite | recommended, for precaching assets |
ext-gd or ext-imagick | only for pwa:icons (SVG requires imagick) |
1. Composer
composer require nyoncode/laravel-pwa
php artisan pwa:installpwa:install publishes config/pwa.php and prints the next steps. The service provider registers itself (package discovery).
2. Layout
Add this to the <head> of your main layout:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
<meta name="csrf-token" content="{{ csrf_token() }}">
<x-pwa::head/>viewport-fit=coverlets content extend under the iPhone display notch; handle the margins withenv(safe-area-inset-*).csrf-tokenis optional, but the client writes the refreshed token into it.
Optionally, add these to your app header:
<x-pwa::nav/>
<x-pwa::install class="btn btn-primary">Install app</x-pwa::install>See Components for details.
3. Icons
php artisan pwa:icons resources/pwa/icon.pngIdeally the source is 1024×1024, square, with the logo centered. The command creates public/pwa/icons/ with 192 and 512 px icons, a maskable icon for Android, apple-touch-icon.png (180 px, with a background), a monochrome icon and a favicon. Add --splash for iOS startup images. The manifest lists only icons that exist on disk.
4. Routes
// routes/web.php
// Login: always "remember me" in the installed app
Route::post('/login', [LoginController::class, 'store'])->middleware('pwa.remember');
// Pages that should work without a connection
Route::middleware(['auth', 'pwa.cache'])->group(function () {
Route::get('/dashboard', DashboardController::class);
Route::get('/orders', [OrderController::class, 'index']);
});With Breeze, Jetstream or Fortify, add pwa.remember to their login route (for Fortify, via Fortify::authenticateThrough() or your own route). See Persistent login.
5. Maintenance mode exceptions
In bootstrap/app.php:
->withMiddleware(function (Middleware $middleware): void {
$middleware->preventRequestsDuringMaintenance(except: [
'manifest.webmanifest',
'sw.js',
'pwa/*',
]);
})Everything works without them too, but keep-alive and the manifest return 503 during maintenance. See Maintenance mode.
6. Deployment
After npm run build in your deploy script:
php artisan pwa:build
php artisan pwa:doctor --cipwa:build is also hooked into php artisan optimize. See Deployment.
7. Verification
php artisan pwa:doctorIt checks HTTPS, icons, scope, the service worker build, maintenance mode exceptions, the session and more. Fix the errors and consider the warnings.
Local development
With APP_ENV=local, the service worker is disabled by default so it does not cache files from the Vite dev server. To test the PWA locally, set:
PWA_ENABLED=trueand run npm run build instead of npm run dev. To test on a phone over the network you need HTTPS (Herd, Valet, a tunnel).
Uninstalling
- Run
php artisan pwa:disable --forceand leave it on until your users come back (their devices unregister the service worker). - Remove the components from your layout and the middleware from your routes.
- Run
composer remove nyoncode/laravel-pwa.
Without step 1, the old service worker stays in browsers until the user deletes it.