nuzlocke-tracker/docs/supabase-auth-setup.md

Supabase Auth Setup

This guide walks through setting up Supabase authentication for local development.

1. Create a Supabase Project

1. Go to supabase.com and sign in
2. Click "New project"
3. Choose your organization, enter a project name (e.g., nuzlocke-tracker-dev), and set a database password
4. Select a region close to you
5. Wait for the project to finish provisioning

2. Get Your Project Credentials

From the Supabase dashboard:

1. Go to Project Settings > API
2. Copy the following values:
   • Project URL -> SUPABASE_URL / VITE_SUPABASE_URL
   • anon public key -> SUPABASE_ANON_KEY / VITE_SUPABASE_ANON_KEY
3. Go to Project Settings > API > JWT Settings
4. Copy the JWT Secret -> SUPABASE_JWT_SECRET

3. Enable Email/Password Auth

1. Go to Authentication > Providers
2. Ensure Email provider is enabled (it's enabled by default)
3. Configure options as needed:
   • Confirm email: Enable for production, disable for local dev convenience
   • Secure email change: Recommended enabled

4. Configure Google OAuth

Google Cloud Console Setup

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Go to APIs & Services > OAuth consent screen
   • Choose "External" user type
   • Fill in app name, user support email, and developer contact
   • Add scopes: email, profile, openid
   • Add test users if in testing mode
4. Go to APIs & Services > Credentials
5. Click Create Credentials > OAuth client ID
6. Select "Web application"
7. Add authorized redirect URIs:
   • https://<your-project-ref>.supabase.co/auth/v1/callback
   • For local dev: http://localhost:5173/auth/callback
8. Copy the Client ID and Client Secret

Supabase Setup

1. Go to Authentication > Providers > Google
2. Enable the provider
3. Paste the Client ID and Client Secret from Google
4. Save

5. Configure Discord OAuth

Discord Developer Portal Setup

1. Go to Discord Developer Portal
2. Click New Application and give it a name
3. Go to OAuth2 > General
4. Add redirect URIs:
   • https://<your-project-ref>.supabase.co/auth/v1/callback
   • For local dev: http://localhost:5173/auth/callback
5. Copy the Client ID and Client Secret

Supabase Setup

1. Go to Authentication > Providers > Discord
2. Enable the provider
3. Paste the Client ID and Client Secret from Discord
4. Save

6. Configure Environment Variables

Backend (.env)

SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_JWT_SECRET=your-jwt-secret-from-dashboard

Frontend (.env)

VITE_SUPABASE_URL=https://your-project-ref.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

7. Configure Redirect URLs

In Supabase Dashboard:

1. Go to Authentication > URL Configuration
2. Set Site URL: http://localhost:5173 (for local dev)
3. Add Redirect URLs:
   • http://localhost:5173/auth/callback
   • http://localhost:5173/** (for flexibility during dev)

For production, add your production URLs here as well.

Verification

After setup, you can verify by:

1. Starting the app with docker compose up
2. Navigating to the login page
3. Testing email/password signup
4. Testing Google and Discord OAuth flows

Troubleshooting

"Invalid redirect URI" error

• Ensure the callback URL in your OAuth provider matches exactly what Supabase expects
• Check that your Site URL in Supabase matches your app's URL

"JWT verification failed"

• Verify SUPABASE_JWT_SECRET matches the one in your Supabase dashboard
• Ensure there are no trailing spaces in your environment variables

OAuth popup closes without logging in

• Check browser console for errors
• Verify the OAuth provider is properly enabled in Supabase
• Ensure redirect URLs are correctly configured in both the OAuth provider and Supabase