ocean-cleanup/CLERK_EMAIL_OPTIONAL_SETUP.md

Clerk Configuration: Email Optional Setup

Overview

This guide explains how to configure Clerk to allow users to sign up and sign in without requiring an email address, while still supporting email as an optional field.

Step-by-Step Configuration

1. Access Clerk Dashboard

1. Go to Clerk Dashboard
2. Select your application
3. Navigate to User & Authentication in the left sidebar

2. Configure Authentication Methods

A. Username Configuration

1. Click on Email, Phone, Username in the left menu
2. Find the Username section
3. Toggle Username to ON
4. Set Username as Required
5. Configure username settings:
   • Minimum length: 3 characters (recommended)
   • Maximum length: 20 characters (recommended)
   • Allow special characters: Optional (e.g., underscores, hyphens)

B. Email Configuration

1. In the same Email, Phone, Username section
2. Find the Email address section
3. Toggle Email address to ON
4. Set Email address as Optional (NOT required)
5. Configure email settings:
   • Email verification: Recommended (when email is provided)
   • Allow disposable emails: Your choice

C. Phone Configuration (Optional)

1. If you want to support phone authentication:
2. Toggle Phone number to ON
3. Set as Optional
4. Configure SMS provider if needed

3. Configure Sign-Up Options

1. Navigate to User & Authentication → Sign-up
2. Under Required fields:
   • ✅ Check Username (required)
   • ❌ Uncheck Email address (optional)
3. Under Optional fields:
   • ✅ Check Email address
   • ✅ Check First name (recommended)
   • ✅ Check Last name (recommended)

4. Configure Sign-In Options

1. Navigate to User & Authentication → Sign-in
2. Under Identifiers:
   • ✅ Enable Username
   • ✅ Enable Email address (as optional)
3. Set Username as the primary identifier
4. Users can sign in with either username or email (if they provided one)

5. Configure Social Connections (Optional)

If you want to support social login:

1. Navigate to User & Authentication → Social connections
2. Enable providers (Google, Facebook, etc.)
3. Note: Social providers typically provide email, but you can configure them to not require it

6. Session & Security Settings

1. Navigate to User & Authentication → Sessions
2. Configure session duration as needed
3. Enable multi-session if desired

7. Customize Sign-Up/Sign-In UI

1. Navigate to Customization → Components
2. Customize the appearance of sign-up/sign-in forms
3. Add custom text to explain that email is optional:
   • "Email is optional but recommended for notifications"
   • "You can add your email later in profile settings"

Testing the Configuration

Test Sign-Up Without Email

1. Go to your application's sign-up page
2. Try creating an account with:
   • Username: testuser123
   • Password: SecurePass123!
   • Leave email blank
3. Sign-up should succeed

Test Sign-In With Username

1. Go to your application's sign-in page
2. Sign in with:
   • Username: testuser123
   • Password: SecurePass123!
3. Sign-in should succeed

Test Adding Email Later

1. Sign in to your application
2. Navigate to user profile settings
3. Add an email address
4. Verify the email (if verification is enabled)
5. Email notifications should now work

Backend Configuration

The backend has been updated to handle optional emails:

Database Schema

model User {
  email String? @unique(map: "email") @db.VarChar(255)
  // email is now nullable
}

User Creation

// Backend automatically handles missing email
email: clerkUser.emailAddresses[0]?.emailAddress || null

Notification Logic

// Email notifications are only sent to users with:
// 1. notificationEmail = true
// 2. email IS NOT NULL
// Users without email only receive in-app notifications

User Experience

For Users Without Email

• ✅ Can sign up with just username and password
• ✅ Can sign in with username
• ✅ Receive in-app notifications
• ❌ Cannot receive email notifications
• 💡 Prompted to add email for full notification support

For Users With Email

• ✅ Can sign up with username and email
• ✅ Can sign in with username or email
• ✅ Receive both in-app and email notifications
• ✅ Full feature access

Notification Behavior

In-App Notifications

• Always work for all users (with or without email)
• Stored in database
• Displayed in notification center
• Real-time updates

Email Notifications

• Only sent to users who:
  1. Have an email address in their profile
  2. Have notificationEmail preference enabled
• Gracefully skipped for users without email
• No errors or warnings for users without email

Profile Settings UI Recommendations

Add to your profile settings page:

// Show email status
{!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>
)}

// Email notification toggle
<label>
  <input
    type="checkbox"
    checked={notificationEmail}
    disabled={!user.email} // Disable if no email
  />
  Email notifications
  {!user.email && (
    <span className="text-gray-500 text-sm ml-2">
      (Add email first)
    </span>
  )}
</label>

Security Considerations

Account Recovery

Without email, users cannot:

• Reset password via email
• Receive account security alerts via email

Recommendations:

1. Encourage users to add email for account security
2. Consider adding phone number as backup
3. Implement security questions as alternative
4. Show warning during sign-up about account recovery

Rate Limiting

Without email verification:

• Implement stricter rate limiting on username sign-ups
• Monitor for abuse (multiple accounts from same IP)
• Consider CAPTCHA for sign-up

Username Validation

Enforce strong username rules:

• Minimum 3 characters
• No offensive words (use profanity filter)
• Unique across platform
• Cannot impersonate system accounts

Monitoring

Track these metrics:

• % of users signing up without email
• % of users adding email later
• Email notification delivery rate
• In-app notification engagement

Troubleshooting

Issue: Users can't sign up without email

Solution: Check Clerk Dashboard → Sign-up → Ensure email is NOT in "Required fields"

Issue: Email notifications failing

Solution: Check that:

1. User has email in database
2. User has notificationEmail = true
3. Email service is configured correctly

Issue: Clerk components still require email

Solution:

1. Clear browser cache
2. Update @clerk/clerk-react to latest version
3. Verify Clerk Dashboard settings saved correctly

Migration for Existing Users

If you have existing users with temporary emails (@temp.com):

-- Find users with temporary emails
SELECT id, email, username FROM users WHERE email LIKE '%@temp.com';

-- Option 1: Set to NULL
UPDATE users SET email = NULL WHERE email LIKE '%@temp.com';

-- Option 2: Keep as-is (they can update in profile)

Support

For issues with Clerk configuration:

• Clerk Documentation
• Clerk Support
• Clerk Discord Community