docs: Add quick start guide for email-optional authentication
This commit is contained in:
157
QUICK_START_EMAIL_OPTIONAL.md
Normal file
157
QUICK_START_EMAIL_OPTIONAL.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# Quick Start: Email-Optional Authentication
|
||||
|
||||
## What Was Done
|
||||
|
||||
✅ Backend is fully configured to support users without email addresses
|
||||
✅ Database schema updated (email is now optional)
|
||||
✅ Notification system handles missing emails gracefully
|
||||
✅ All code changes committed and pushed to git
|
||||
|
||||
## What You Need To Do
|
||||
|
||||
### 1. Configure Clerk Dashboard (5 minutes)
|
||||
|
||||
Go to [Clerk Dashboard](https://dashboard.clerk.com) and configure:
|
||||
|
||||
**User & Authentication → Email, Phone, Username:**
|
||||
- ✅ Username: **ON** and **Required**
|
||||
- ✅ Email: **ON** but **Optional** (not required)
|
||||
|
||||
**User & Authentication → Sign-up:**
|
||||
- Required fields: ✅ Username only
|
||||
- Optional fields: ✅ Email, First name, Last name
|
||||
|
||||
**User & Authentication → Sign-in:**
|
||||
- Identifiers: ✅ Username (primary), ✅ Email (optional)
|
||||
|
||||
📖 **Detailed guide**: See `CLERK_EMAIL_OPTIONAL_SETUP.md`
|
||||
|
||||
### 2. Test It Works
|
||||
|
||||
**Test 1: Sign up without email**
|
||||
```
|
||||
1. Go to your sign-up page
|
||||
2. Enter username: testuser123
|
||||
3. Enter password: SecurePass123!
|
||||
4. Leave email blank
|
||||
5. Should succeed ✅
|
||||
```
|
||||
|
||||
**Test 2: Notifications work**
|
||||
```
|
||||
1. Sign in as user without email
|
||||
2. Create a report or event
|
||||
3. Check in-app notifications → Should work ✅
|
||||
4. Check email → Should not be sent (no errors) ✅
|
||||
```
|
||||
|
||||
**Test 3: Run automated test**
|
||||
```bash
|
||||
cd server
|
||||
npx ts-node src/scripts/testEmailOptional.ts
|
||||
```
|
||||
|
||||
### 3. Optional: Update Frontend UI
|
||||
|
||||
Add to profile settings to show email status:
|
||||
|
||||
```typescript
|
||||
// Show prompt to add email
|
||||
{!user.email && (
|
||||
<div className="bg-yellow-50 border border-yellow-200 rounded-lg p-4">
|
||||
<p className="text-sm text-yellow-800">
|
||||
📧 Add an email address to receive email notifications
|
||||
</p>
|
||||
</div>
|
||||
)}
|
||||
|
||||
// Disable email notification toggle if no email
|
||||
<label>
|
||||
<input
|
||||
type="checkbox"
|
||||
checked={notificationEmail}
|
||||
disabled={!user.email}
|
||||
/>
|
||||
Email notifications
|
||||
{!user.email && <span className="text-sm text-gray-500 ml-2">(Add email first)</span>}
|
||||
</label>
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
### Users Without Email
|
||||
- ✅ Sign up with username + password only
|
||||
- ✅ Sign in with username
|
||||
- ✅ Receive in-app notifications
|
||||
- ❌ Cannot receive email notifications (gracefully skipped)
|
||||
|
||||
### Users With Email
|
||||
- ✅ Sign up with username + email + password
|
||||
- ✅ Sign in with username or email
|
||||
- ✅ Receive both in-app and email notifications
|
||||
|
||||
### Notification Logic
|
||||
```typescript
|
||||
// Backend automatically filters users
|
||||
const users = await prisma.user.findMany({
|
||||
where: {
|
||||
notificationEmail: true,
|
||||
email: { not: null }, // Only users with email
|
||||
},
|
||||
});
|
||||
|
||||
// Email service validates before sending
|
||||
if (!to || to.trim() === '') {
|
||||
console.log('Skipping - no email address');
|
||||
return false;
|
||||
}
|
||||
```
|
||||
|
||||
## Files Changed
|
||||
|
||||
**Backend:**
|
||||
- `server/prisma/schema.prisma` - Email now optional
|
||||
- `server/src/services/userService.ts` - Handle null email
|
||||
- `server/src/services/notificationService.ts` - Filter by email
|
||||
- `server/src/services/emailService.ts` - Validate email
|
||||
- `server/src/controllers/eventController.ts` - Handle null email
|
||||
- `server/src/controllers/reportController.ts` - Handle null email
|
||||
|
||||
**Documentation:**
|
||||
- `EMAIL_OPTIONAL_IMPLEMENTATION.md` - Technical details
|
||||
- `CLERK_EMAIL_OPTIONAL_SETUP.md` - Clerk configuration guide
|
||||
- `TASK_EMAIL_OPTIONAL_COMPLETE.md` - Complete summary
|
||||
- `QUICK_START_EMAIL_OPTIONAL.md` - This file
|
||||
|
||||
**Testing:**
|
||||
- `server/src/scripts/testEmailOptional.ts` - Test script
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Issue**: Users still required to enter email
|
||||
- **Fix**: Check Clerk Dashboard → Sign-up → Email should be in "Optional fields", not "Required fields"
|
||||
|
||||
**Issue**: Email notifications failing
|
||||
- **Fix**: Check user has email in database: `SELECT email FROM users WHERE id = 'user_id'`
|
||||
|
||||
**Issue**: Errors when sending notifications
|
||||
- **Fix**: Check logs - should see "Skipping email for user X (no email address)" - this is normal
|
||||
|
||||
## Support
|
||||
|
||||
- 📖 Full documentation: `CLERK_EMAIL_OPTIONAL_SETUP.md`
|
||||
- 🧪 Test script: `server/src/scripts/testEmailOptional.ts`
|
||||
- 📝 Implementation details: `EMAIL_OPTIONAL_IMPLEMENTATION.md`
|
||||
- ✅ Task summary: `TASK_EMAIL_OPTIONAL_COMPLETE.md`
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ Configure Clerk Dashboard (see above)
|
||||
2. ✅ Test sign-up without email
|
||||
3. ✅ Test notifications work
|
||||
4. ⏳ Optional: Update frontend UI
|
||||
5. ⏳ Monitor user adoption
|
||||
|
||||
---
|
||||
|
||||
**Status**: ✅ Backend complete | ⏳ Clerk configuration needed (manual step)
|
||||
Reference in New Issue
Block a user