Paul Bailey
7cda58440f
- Add self-hosted push notifications using VAPID (no external services) - Create PushSubscription model in database - Implement server-side push logic with web-push library - Add notification helpers for list events (items, invitations, collaborators) - Create NotificationSettings UI component for profile page - Add usePushNotifications React hook for subscription management - Create API routes for subscription management and VAPID key - Update service worker with push event handlers - Integrate notifications into item actions (add, remove, complete) - Integrate notifications into sharing actions (invite, accept, remove) - Add VAPID key generation script - Add comprehensive documentation and setup guides Notifications are sent when: - Items are added/removed/completed in shared lists - Users are invited to lists - Invitations are accepted - Collaborators are removed from lists Works on iOS 16.4+ (when installed to home screen), Android, and desktop browsers.
2.4 KiB
2.4 KiB
Web Push Notifications Implementation Guide
Overview
This guide explains how to implement Web Push notifications in your PWA using VAPID (self-hosted, no external service needed).
Architecture
- VAPID Keys: Generate once, store securely (like JWT secrets)
- Client: Request permission, subscribe to push notifications
- Database: Store push subscriptions per user
- Server: Send notifications when list events occur
- Service Worker: Receive and display notifications
Setup Steps
1. Generate VAPID Keys
Run this once to generate your VAPID keys:
npx web-push generate-vapid-keys
Add to .env:
VAPID_PUBLIC_KEY=your_public_key_here
VAPID_PRIVATE_KEY=your_private_key_here
VAPID_SUBJECT=mailto:your-email@example.com
2. Install Dependencies
npm install web-push
3. Database Schema
Add PushSubscription model to store user subscriptions (see prisma/schema.prisma changes).
4. Client-Side Flow
- User grants notification permission
- Service worker subscribes to push manager
- Subscription sent to server and stored in database
- Server sends notifications when events occur
- Service worker displays notifications
5. Notification Triggers
Notifications are sent when:
- Someone adds/removes an item from a shared list
- Someone invites you to a list
- Someone accepts your list invitation
- Someone removes you from a list
Testing
Local Testing
- Use Chrome DevTools > Application > Service Workers
- Use Chrome DevTools > Application > Push Messaging to simulate
iOS Testing
- Must be installed to home screen
- iOS 16.4+ required
- Test on actual device (simulator doesn't support push)
Android Testing
- Works in browser and installed PWA
- Test on actual device for best results
Privacy & Best Practices
- Always request permission explicitly (don't auto-prompt)
- Allow users to disable notifications
- Store subscriptions securely
- Handle subscription expiration/updates
- Respect user preferences per list
Troubleshooting
Notifications not appearing
- Check permission status
- Verify service worker is active
- Check browser console for errors
- Ensure VAPID keys are correct
iOS specific issues
- Must be installed to home screen
- Check iOS version (16.4+)
- Verify manifest.json is correct
Subscription fails
- Check VAPID public key matches server
- Verify service worker scope
- Check network requests in DevTools