mirror of
https://github.com/xtr-dev/payload-notifications.git
synced 2025-12-10 02:43:23 +00:00
Add initial plugin implementation and development setup
This commit is contained in:
220
dev/README.md
Normal file
220
dev/README.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# Payload Notifications Plugin - Development Environment
|
||||
|
||||
This is the development environment for testing and demonstrating the `@xtr-dev/payload-notifications` plugin.
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
1. **Install dependencies:**
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
2. **Start the development server:**
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
3. **Open the demo:**
|
||||
- Homepage: [http://localhost:3000](http://localhost:3000)
|
||||
- Admin Panel: [http://localhost:3000/admin](http://localhost:3000/admin)
|
||||
- Push Demo: [http://localhost:3000/demo](http://localhost:3000/demo)
|
||||
|
||||
4. **Login to admin:**
|
||||
- Email: `dev@payloadcms.com`
|
||||
- Password: `test`
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
The dev environment showcases a complete implementation of the notifications plugin with:
|
||||
|
||||
### Collections
|
||||
- **Users** - Authentication with admin/customer roles
|
||||
- **Products** - Sample e-commerce products
|
||||
- **Orders** - Sample orders with different statuses
|
||||
- **Posts** - Blog posts for content notifications
|
||||
- **Notifications** - The plugin's notifications collection
|
||||
- **Push Subscriptions** - Web push subscription management
|
||||
|
||||
### Plugin Configuration
|
||||
```typescript
|
||||
notificationsPlugin({
|
||||
collections: {
|
||||
slug: 'notifications',
|
||||
labels: { singular: 'Notification', plural: 'Notifications' }
|
||||
},
|
||||
relationships: [
|
||||
{ name: 'order', relationTo: 'orders', label: 'Related Order' },
|
||||
{ name: 'product', relationTo: 'products', label: 'Related Product', hasMany: true },
|
||||
{ name: 'post', relationTo: 'posts', label: 'Related Post' }
|
||||
],
|
||||
access: {
|
||||
read: ({ req }) => Boolean(req.user),
|
||||
create: ({ req }) => Boolean(req.user),
|
||||
update: ({ req }) => Boolean(req.user),
|
||||
delete: ({ req }) => Boolean(req.user?.role === 'admin'),
|
||||
},
|
||||
webPush: {
|
||||
enabled: true,
|
||||
vapidPublicKey: process.env.VAPID_PUBLIC_KEY,
|
||||
vapidPrivateKey: process.env.VAPID_PRIVATE_KEY,
|
||||
vapidSubject: 'mailto:test@example.com'
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## 📱 Web Push Notifications
|
||||
|
||||
### Setup VAPID Keys
|
||||
|
||||
1. **Generate VAPID keys:**
|
||||
```bash
|
||||
npx web-push generate-vapid-keys
|
||||
```
|
||||
|
||||
2. **Create a `.env` file:**
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
3. **Add your VAPID keys to `.env`:**
|
||||
```env
|
||||
VAPID_PUBLIC_KEY=your-public-key
|
||||
VAPID_PRIVATE_KEY=your-private-key
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
The plugin automatically creates these endpoints:
|
||||
|
||||
- `POST /api/push-notifications/subscribe` - Subscribe to push notifications
|
||||
- `POST /api/push-notifications/unsubscribe` - Unsubscribe from push notifications
|
||||
- `GET /api/push-notifications/vapid-public-key` - Get VAPID public key
|
||||
- `POST /api/push-notifications/send` - Send notification to user
|
||||
- `POST /api/push-notifications/test` - Send test notification (admin only)
|
||||
- `POST /api/push-notifications/track` - Track notification events
|
||||
|
||||
### Service Worker Setup
|
||||
|
||||
The service worker is already configured and located at `/public/sw.js`. For new projects, generate it with:
|
||||
|
||||
```bash
|
||||
npx @xtr-dev/payload-notifications generate-sw
|
||||
```
|
||||
|
||||
The service worker handles:
|
||||
|
||||
- **Push message processing** - Receives and displays push notifications
|
||||
- **Notification clicks** - Opens relevant admin panel or URLs
|
||||
- **Test notifications** - Supports demo functionality
|
||||
- **Analytics tracking** - Tracks notification interactions
|
||||
|
||||
### Testing Push Notifications
|
||||
|
||||
1. **Open the [demo page](http://localhost:3000/demo)**
|
||||
2. **Enable notifications:**
|
||||
- Click "Enable Notifications"
|
||||
- Allow browser permissions when prompted
|
||||
- The service worker will be registered automatically
|
||||
3. **Test the system:**
|
||||
- Click "Send Test Notification" to see instant notifications
|
||||
- Check browser dev tools console for service worker logs
|
||||
4. **Admin panel testing:**
|
||||
- Go to `/admin` and create notifications
|
||||
- Attach relationships to orders, products, or posts
|
||||
- Real push notifications require proper VAPID keys
|
||||
|
||||
### Service Worker Features
|
||||
|
||||
- ✅ **Automatic registration** when subscribing to notifications
|
||||
- ✅ **Test notification support** for immediate testing
|
||||
- ✅ **Rich notification display** with actions and custom icons
|
||||
- ✅ **Click handling** that opens relevant admin pages
|
||||
- ✅ **Analytics tracking** for notification interactions
|
||||
- ✅ **Fallback handling** for missing icons or data
|
||||
|
||||
## 📊 Sample Data
|
||||
|
||||
The development environment is automatically seeded with:
|
||||
|
||||
### Users
|
||||
- **Admin User**: dev@payloadcms.com (password: test)
|
||||
- **Customer User**: customer@example.com (password: test)
|
||||
|
||||
### Products
|
||||
- Wireless Headphones ($299.99)
|
||||
- Cotton T-Shirt ($24.99)
|
||||
- JavaScript Guide ($39.99)
|
||||
|
||||
### Orders
|
||||
- Order #ORD-001 (Shipped - Headphones + T-Shirt)
|
||||
- Order #ORD-002 (Pending - JavaScript Guide)
|
||||
|
||||
### Notifications
|
||||
- Welcome notification with blog post attachment
|
||||
- Order shipped notification with order and product attachments
|
||||
- Product recommendation notification (marked as read)
|
||||
|
||||
## 🛠️ Development
|
||||
|
||||
### File Structure
|
||||
```
|
||||
dev/
|
||||
├── app/
|
||||
│ ├── (app)/
|
||||
│ │ ├── page.tsx # Homepage
|
||||
│ │ └── demo/
|
||||
│ │ └── page.tsx # Push notifications demo
|
||||
│ └── (payload)/
|
||||
│ ├── admin/ # Payload admin panel
|
||||
│ └── api/ # API routes
|
||||
├── helpers/
|
||||
│ ├── credentials.ts # Default user credentials
|
||||
│ └── testEmailAdapter.ts # Email testing
|
||||
├── payload.config.ts # Payload configuration
|
||||
├── seed.ts # Database seeding
|
||||
└── .env.example # Environment variables template
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
- `DATABASE_URI` - MongoDB connection string (optional, uses in-memory DB)
|
||||
- `PAYLOAD_SECRET` - JWT secret for authentication
|
||||
- `VAPID_PUBLIC_KEY` - VAPID public key for web push
|
||||
- `VAPID_PRIVATE_KEY` - VAPID private key for web push
|
||||
- `NODE_ENV` - Environment (development/production)
|
||||
|
||||
### Scripts
|
||||
- `pnpm dev` - Start development server
|
||||
- `pnpm build` - Build the application
|
||||
- `pnpm start` - Start production server
|
||||
- `pnpm lint` - Run ESLint
|
||||
- `pnpm test` - Run tests
|
||||
|
||||
## 🔍 Testing the Plugin
|
||||
|
||||
1. **Admin Panel Testing:**
|
||||
- Create notifications with different relationship attachments
|
||||
- Test read/unread functionality
|
||||
- View push subscriptions
|
||||
- Test user role permissions
|
||||
|
||||
2. **API Testing:**
|
||||
- Test push notification endpoints
|
||||
- Subscribe/unsubscribe from push notifications
|
||||
- Send test notifications
|
||||
|
||||
3. **Client Integration:**
|
||||
- Test the demo page functionality
|
||||
- Test push notification permissions
|
||||
- Test service worker integration
|
||||
|
||||
## 🚀 Production Deployment
|
||||
|
||||
1. Set up a real MongoDB database
|
||||
2. Configure proper VAPID keys
|
||||
3. Set up SSL certificates for push notifications
|
||||
4. Configure proper environment variables
|
||||
5. Deploy using your preferred platform
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
For complete documentation, see the main [README.md](../README.md) file.
|
||||
Reference in New Issue
Block a user