Development¶

This page explains how to debug and monitor your PWA during development.

The bundle integrates with Symfony's Web Debug Toolbar, providing a dedicated PWA panel for inspecting your Progressive Web App configuration.

Manifest Tab: - Current manifest configuration - App metadata (name, icons, colors, display mode) - Installability status - Generated manifest JSON - Icon verification

Service Worker Tab: - Service worker status and registration - Caching strategies configured - Workbox configuration - Active cache names - Custom rules applied

Icons & Assets: - Generated icons (all sizes and formats) - Favicon status - Screenshot images - Startup images (iOS)

Installability checker¶

The toolbar includes an installability checker that analyzes your PWA configuration:

Green status: App meets installation requirements
Yellow status: App partially meets requirements (may work on some platforms)
Red status: Missing required configuration

Warning

Browser installation requirements change frequently. The bundle's installability indicator is a guide, but actual installation availability depends on the browser and platform.

Service worker debugging¶

Debugging service workers requires a different approach than regular JavaScript.

Development mode features¶

In development (APP_ENV=dev), the service worker includes:

Verbose Logging: - All Workbox operations logged to console - Cache hit/miss information - Route matching details - Background sync status

Inline Comments: - Explanation of each caching strategy - Route pattern documentation - Custom rule descriptions

Browser DevTools¶

Chrome/Edge DevTools: 1. Open DevTools (F12) 2. Go to Application tab 3. Select Service Workers in the sidebar

From here you can: - See registration status - Unregister the service worker - Update on reload - Bypass for network - View cached resources in Cache Storage

Firefox DevTools: 1. Open DevTools (F12) 2. Go to Application tab (or about:debugging#/runtime/this-firefox) 3. View service workers and storage

Common debugging tasks¶

Force Service Worker Update:

// In browser console
navigator.serviceWorker.getRegistrations().then(registrations => {
    registrations.forEach(reg => reg.update());
});

Clear All Caches:

// In browser console
caches.keys().then(names => {
    names.forEach(name => caches.delete(name));
});

Check Current Service Worker:

// In browser console
navigator.serviceWorker.controller

Production mode¶

In production (APP_ENV=prod), the service worker is optimized:

All debugging code removed
Comments stripped out
Console logging disabled

Logging configuration¶

The bundle uses PSR-3 logging to record important events and errors.

Default logger¶

By default, the bundle uses Symfony's default logger channel.

Custom logger¶

Configure a custom logger for PWA-specific logging:

config/packages/pwa.yaml

pwa:
    logger: 'monolog.logger.pwa'

Then define the logger in your Monolog configuration:

config/packages/monolog.yaml

monolog:
    channels: ['pwa']

    handlers:
        pwa:
            type: stream
            path: '%kernel.logs_dir%/pwa.log'
            level: debug
            channels: ['pwa']

What gets logged¶

The bundle logs: - Manifest compilation events - Service worker generation - Icon processing - Asset compilation - Configuration errors - Runtime warnings

Logging levels¶

DEBUG: Detailed processing information (development only)
INFO: Normal operational messages
WARNING: Non-critical issues (e.g., missing optional config)
ERROR: Critical problems that prevent PWA functionality

Development tips¶

Testing offline mode¶

Method 1: Browser DevTools 1. Open DevTools → Network tab 2. Check "Offline" checkbox 3. Reload the page

Method 2: Throttling 1. Open DevTools → Network tab 2. Select "Slow 3G" or "Fast 3G" 3. Test performance with limited connectivity

Testing installation¶

Desktop: 1. Open your app in Chrome/Edge 2. Look for install icon in address bar 3. Click to test installation flow

Mobile: 1. Visit your app on a real device or emulator 2. Look for "Add to Home Screen" prompt 3. Test the installed app experience

Cache inspection¶

View cached resources: 1. DevTools → Application tab 2. Expand Cache Storage in sidebar 3. Click on cache names to see contents 4. Right-click resources to delete

Manifest validation¶

Validate your manifest: 1. DevTools → Application tab 2. Click Manifest in sidebar 3. Review all properties 4. Check for warnings or errors

Testing updates¶

Test how your PWA handles updates:

Make a change to your service worker config
Deploy the update
Reload the app
Check that service worker updates
Verify new version activates

Use skip_waiting: false in config to test manual update flows.

Common development issues¶

Manifest not loading¶

Symptoms: Manifest link appears in HTML but DevTools shows "No manifest detected"

Solutions: 1. Clear browser cache 2. Check manifest URL is accessible 3. Verify JSON syntax (use a JSON validator) 4. Ensure {{ pwa() }} is in <head> section

Service worker not updating¶

Symptoms: Changes to service worker don't appear

Solutions: 1. Hard refresh (Ctrl+Shift+R / Cmd+Shift+R) 2. Click "Update" in DevTools → Application → Service Workers 3. Check "Update on reload" in DevTools 4. Unregister and re-register the service worker

Install prompt not showing¶

Symptoms: No install option appears

Check: 1. HTTPS is enabled (or using localhost) 2. Manifest has required properties 3. Service worker is registered 4. No console errors 5. User engagement criteria met (varies by browser)

Caching issues¶

Symptoms: Old content still showing after updates

Solutions: 1. Update cache version in service worker config 2. Clear cache storage in DevTools 3. Implement cache expiration strategies 4. Use cache-first only for static assets

Best practices for development¶

Use HTTPS locally: Use symfony serve with TLS or configure a local SSL certificate
Test on real devices: Emulators don't perfectly match real device behavior
Monitor console: Watch for service worker errors and warnings
Clear cache regularly: Prevent stale data during development
Test offline scenarios: Ensure graceful degradation
Validate manifest: Use browser DevTools and online validators
Version your caches: Update cache names when content changes