Search by

nyoncode / laravel-pwa

NyonCode

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.

v0.4.0 2026-11-21 19:10 UTC

This package is auto-updated.

Last update: 2026-11-21 20:25:09 UTC


README

Latest version Tests Static analysis PHPStan level max PHP 8.2+ Laravel 12 | 13 License: MIT

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.cache middleware. 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 503 from a network failure, shows your maintenance screen and keeps the cache intact. php artisan pwa:down wraps artisan 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:disable removes 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-ui with Back and Reload buttons; phones, tablets and Safari get standalone. 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.