Getting Started

Minimal Setup

Install the package:
```
composer require erag/laravel-pwa
```
Publish configuration:
```
php artisan erag:install-pwa
```

Add Blade directives to your main layout (resources/views/layouts/app.blade.php):

<head>
    @PwaHead
    <!-- Other head tags -->
</head>
<body>
    <!-- Content -->
    @RegisterServiceWorkerScript
</body>

First Use Case: Basic PWA Activation

Configure config/pwa.php with your app’s name, icons, and theme colors.
Run php artisan erag:update-manifest to generate manifest.json and sw.js in public/.
Test on Chrome/Android: Visit your site, open DevTools (Ctrl+Shift+I), and check the "Application" tab for PWA registration.

Implementation Patterns

Core Workflow

Configuration-Driven Setup:
- Define PWA settings in config/pwa.php (name, icons, theme colors, etc.).
- Use the facade (PWA::update()) to dynamically modify settings at runtime (e.g., for multi-tenancy).
Frontend Integration:
- Blade Directives:
  - @PwaHead: Injects <link rel="manifest">, theme colors, and meta tags.
  - @RegisterServiceWorkerScript: Registers the service worker with fallback logic.
- Livewire/Vue/React: Works out-of-the-box with existing frontend stacks. For Livewire, set 'livewire-app' => true in config.
Dynamic Updates:
- Update manifest/icons via:
```
PWA::update(['name' => 'New App Name']);
PWA::processLogo($request); // For file uploads
```
- Trigger updates via controllers, commands, or events (e.g., after logo uploads).
Offline Support:
- Customize resources/views/vendor/pwa/offline.blade.php for offline pages.
- Pre-cache critical assets by extending the service worker (public/sw.js).

Integration Tips

HTTPS Requirement: Ensure your site uses HTTPS (PWA features fail otherwise). Use tools like Laravel Forge or Cloudflare for local testing.
Icon Optimization: Use RealFaviconGenerator to create multi-size icons (add all sizes to config/pwa.php).

Service Worker Customization: Override public/sw.js to add custom caching logic (e.g., for API routes):

// public/sw.js
self.addEventListener('fetch', (event) => {
    if (event.request.url.includes('/api/')) {
        event.respondWith(caches.match(event.request));
    }
});

Debugging: Enable debug: true in config/pwa.php to log service worker events to the console.

Gotchas and Tips

Pitfalls

Service Worker Registration:

Issue: Service worker fails to register on iOS/Safari due to strict security policies.

Fix: Ensure your site is served over HTTPS and use the scope parameter in sw.js:

// public/sw.js
if ('serviceWorker' in navigator) {
    window.addEventListener('load', () => {
        navigator.serviceWorker.register('/sw.js', { scope: '/' }).catch(err => {
            console.error('Service Worker registration failed: ', err);
        });
    });
}

iOS Workaround: Add this to your manifest.json:

{
  "display": "standalone",
  "scope": "/",
  "start_url": "/"
}

Manifest Updates:
- Issue: Changes to config/pwa.php don’t reflect in manifest.json until you run php artisan erag:update-manifest.
- Fix: Cache the manifest file or use a file watcher (e.g., Laravel Mix) to auto-update during development.
Livewire Compatibility:
- Issue: Livewire apps may not trigger PWA updates correctly.
- Fix: Set 'livewire-app' => true in config/pwa.php and ensure Livewire’s Alpine.js doesn’t interfere with service worker registration.

Offline Page:

Issue: Custom offline.blade.php isn’t served when offline.

Fix: Verify the service worker’s fetch event handler:

self.addEventListener('fetch', (event) => {
    event.respondWith(
        caches.match(event.request).then((response) => {
            return response || fetch(event.request);
        })
    );
});

Debugging Tips

Service Worker Debugging:
- Open Chrome DevTools (Application > Service Workers), reload the page, and check the "Registered" status.
- Use navigator.serviceWorker.controller to inspect the active worker.
Manifest Validation:
- Validate your manifest.json using Google’s PWA Checker.
- Common errors: Missing short_name, invalid icon sizes, or incorrect start_url.
Logo Uploads:
- Ensure uploaded logos meet requirements (PNG, 512x512px, <1024KB). Validate with:
```
$request->validate([
    'logo' => 'required|image|mimes:png|max:1024',
]);
```

Extension Points

Custom Service Worker:
- Override public/sw.js to add logic like:
  - Background sync for forms.
  - Custom caching strategies (e.g., stale-while-revalidate).
- Example: Cache API responses for 24 hours:
```
caches.open('api-cache').then((cache) => {
    return fetch('/api/data')
        .then((response) => cache.put('/api/data', response.clone()))
        .then(() => response);
});
```

Dynamic Manifests:

Use the facade to update manifests per user/tenant:

PWA::update([
    'name' => Auth::user()->company_name,
    'theme_color' => Auth::user()->preferred_color,
]);

Push Notifications:

Extend the service worker to handle push events:

self.addEventListener('push', (event) => {
    const data = event.data.json();
    event.waitUntil(
        self.registration.showNotification(data.title, {
            body: data.body,
            icon: '/logo.png',
        })
    );
});

Requires additional setup (e.g., Firebase Cloud Messaging).

Local Development:
- Use laravel-valet with HTTPS or configure trusted-proxies in config/app.php for local PWA testing:
```
'trusted_proxies' => ['127.0.0.1', '::1'],
```

Laravel Pwa Laravel Package