Dynamic Site URL Configuration for Convex Auth

This guide explains how to configure dynamic site URLs for Convex Auth across different development and deployment environments.

Problem

When using different dev servers or deployment environments, the SITE_URL needs to change dynamically to match the current environment. This affects:

• OAuth redirect URLs
• Magic link destinations
• Email verification links

Solutions

1. Environment-Based Configuration (Recommended)

Set different SITE_URL values for each Convex deployment:

# Development
npx convex env set SITE_URL http://localhost:3000

# Preview/Staging (for branch deployments)
npx convex deploy --preview
npx convex env set SITE_URL https://preview-branch-name.yourdomain.com

# Production
npx convex env set SITE_URL https://yourdomain.com --prod

2. Multiple Local Development Ports

If you need to support multiple local development ports:

// In convex/auth.ts
callbacks: {
  async redirect({ redirectTo }) {
    const localPorts = ['3000', '3001', '3002', '5173'];
    const allowedOrigins = [
      process.env.SITE_URL,
      ...localPorts.map(port => `http://localhost:${port}`),
    ].filter(Boolean);

    // Handle relative redirects
    if (redirectTo.startsWith('/')) {
      return `${process.env.SITE_URL}${redirectTo}`;
    }

    // Validate absolute URLs
    const isAllowed = allowedOrigins.some(origin => 
      redirectTo.startsWith(origin)
    );

    if (!isAllowed) {
      throw new Error(`Invalid redirectTo URL: ${redirectTo}`);
    }

    return redirectTo;
  }
}

3. Branch-Based Deployments

Use Convex preview deployments for each Git branch:

# Create a preview deployment for current branch
npx convex deploy --preview

# The deployment URL will be something like:
# https://careful-elephant-123.convex.cloud

# Set the SITE_URL for this preview
npx convex env set SITE_URL https://your-branch.preview.yourdomain.com

4. OAuth Provider Configuration

When using OAuth providers, you'll need to update the redirect URLs in each provider's settings:

GitHub OAuth

Add these redirect URLs to your GitHub OAuth app:

• http://localhost:3000/api/auth/callback/github
• https://dev.yourdomain.com/api/auth/callback/github
• https://staging.yourdomain.com/api/auth/callback/github
• https://yourdomain.com/api/auth/callback/github

Google OAuth

Add authorized redirect URIs in Google Cloud Console:

• http://localhost:3000/api/auth/callback/google
• https://dev.yourdomain.com/api/auth/callback/google
• etc.

5. Email Provider Configuration

For email providers like Resend, the SITE_URL is used to generate verification links. The ResendOTP provider will automatically use the configured SITE_URL.

6. Client-Side Configuration

Ensure your client-side code uses the correct Convex deployment URL:

// In your client provider
const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL);

Set different values in your .env files:

# .env.development
NEXT_PUBLIC_CONVEX_URL=https://dev-deployment.convex.cloud

# .env.production
NEXT_PUBLIC_CONVEX_URL=https://prod-deployment.convex.cloud

Best Practices

1. Use separate Convex deployments for dev, staging, and production
2. Document all environment variables required for each environment
3. Automate deployment with CI/CD to ensure correct environment variables
4. Test OAuth flows in each environment after configuration
5. Use preview deployments for pull request testing

Example Deployment Workflow

# 1. Development
npm run dev
# Uses SITE_URL=http://localhost:3000

# 2. Preview (for PR)
git checkout -b feature/new-feature
npx convex deploy --preview
npx convex env set SITE_URL https://pr-123.preview.yourdomain.com

# 3. Staging
git checkout staging
npx convex deploy --deployment staging
npx convex env set SITE_URL https://staging.yourdomain.com --deployment staging

# 4. Production
git checkout main
npx convex deploy --prod
# SITE_URL already set to https://yourdomain.com

Troubleshooting

1. OAuth redirect mismatch: Ensure the OAuth provider has all possible redirect URLs configured
2. Email links not working: Check that SITE_URL is set correctly for the deployment
3. Wrong redirect after login: Verify the redirect callback is handling all your domains

Security Considerations

1. Always validate redirect URLs in the redirect callback
2. Use HTTPS in production for all site URLs
3. Limit allowed domains to only those you control
4. Don't expose internal URLs in production builds