alphaonedev/web-pwa

web-pwa

Purpose

This skill enables building Progressive Web Apps (PWAs) by managing service workers, caching, manifests, offline functionality, background sync, and push notifications. It focuses on making web apps installable, reliable, and engaging like native apps.

When to Use

Use this skill when developing web apps that need offline access, such as news readers or e-commerce sites; for apps requiring push notifications, like chat apps; or when enhancing user experience with background sync for data updates. Apply it in scenarios where users expect app-like behavior on mobile or desktop browsers.

Key Capabilities

• Service Workers: Intercept network requests and cache responses using the Cache API (e.g., caches.open('my-cache')).
• Manifest: Define app metadata in a JSON file (e.g., { "name": "My PWA", "start_url": "/" }) for installability.
• Offline Support: Enable apps to function without internet via service workers and IndexedDB.
• Background Sync: Queue tasks for later execution when online, using the Background Sync API (e.g., registration.sync.register('my-sync')).
• Push Notifications: Handle subscriptions and messages via the Push API and Service Worker API (e.g., subscription.endpoint for server communication).

Usage Patterns

To implement a PWA, first create a service worker file (e.g., sw.js) and register it in your main script. For offline caching, use the Cache API to store assets. Always check for service worker support before registration. Integrate a web app manifest for installation prompts. Test patterns in a browser's dev tools under the Application tab.

Common Commands/API

• Register a service worker: Use if ('serviceWorker' in navigator) { navigator.serviceWorker.register('/sw.js'); } in your JavaScript file.
• Cache assets: In sw.js, add event.respondWith(caches.match(event.request).then(response => response || fetch(event.request))); to handle requests.
• Add to home screen: Ensure manifest.json includes "display": "standalone" and serve it from the root.
• Handle push notifications: Subscribe with registration.pushManager.subscribe({ userVisibleOnly: true }) and send via a server endpoint like https://yourserver.com/push (requires $VAPID_PUBLIC_KEY for authentication).
• Background sync: Register with navigator.serviceWorker.ready.then(reg => reg.sync.register('sync-tag')); use CLI tools like workbox-cli build for bundling (e.g., npx workbox generateSW workbox-config.js). Config format for manifest: JSON object like { "short_name": "App", "icons": [{ "src": "icon.png", "sizes": "192x192" }] }.

Integration Notes

Integrate this skill with existing web projects by adding a service worker script and manifest file. For push notifications, set up a server with the Web Push library and use env vars like $VAPID_PRIVATE_KEY for signing. If using frameworks, import in React via useEffect(() => { if ('serviceWorker' in navigator) navigator.serviceWorker.register(); }, []);. For caching, combine with Fetch API; ensure HTTPS for service workers. Avoid conflicts by checking for existing workers before registration.

Error Handling

When registering service workers, catch errors with .then(() => console.log('Registered')).catch(err => console.error('Registration failed:', err)). For cache operations, handle promise rejections (e.g., caches.open('cache-name').then(cache => cache.addAll(['/'])).catch(err => console.error(err))). If push subscription fails, check user permissions and use Notification.requestPermission() first. For background sync, listen for sync events in the service worker and handle failures by retrying or logging with event.tag. Use browser-specific error codes, like DOMException for security errors, and set up global error handlers in your app.

Concrete Usage Examples

1. Basic PWA Setup: Create a service worker to cache static assets. In index.js: if ('serviceWorker' in navigator) { navigator.serviceWorker.register('/sw.js').then(reg => console.log('SW registered')); }. In sw.js: self.addEventListener('install', event => event.waitUntil(caches.open('static').then(cache => cache.add('/'))));. This enables offline loading of the home page.
2. Push Notifications Integration: Subscribe users and handle messages. In your app: registration.pushManager.subscribe().then(sub => fetch('/subscribe', { method: 'POST', body: JSON.stringify(sub) }));. On the server, use an endpoint like POST /subscribe with $VAPID_PUBLIC_KEY to send notifications via the Push API.

Graph Relationships

• Related to cluster: web-dev (e.g., shares dependencies with skills like web-frontend, web-backend).
• Connected via tags: pwa (links to mobile-app), service-worker (links to web-performance), offline (links to data-sync), web (links to full-stack-dev).
• Dependencies: Requires web APIs; integrates with tools like Workbox for service worker generation.