Skip to content

NEON_AUTH_MIGRATION.md

Latest commit

 

History

History
167 lines (118 loc) · 4.18 KB

NEON_AUTH_MIGRATION.md

File metadata and controls

167 lines (118 loc) · 4.18 KB

Neon Auth (Stack Auth) Migration Guide

This document outlines the migration from Clerk authentication to Neon Auth (powered by Stack Auth).

Overview

The application has been migrated to use Neon Auth, which provides seamless integration with Neon's PostgreSQL database and automatic user data synchronization.

Key Changes

Frontend Changes

  1. Dependencies

    • Removed: @clerk/clerk-react
    • Added: @stackframe/react

  2. Configuration

    • New Stack client configuration in src/lib/stack.ts
    • Updated environment variables (see below)

  3. Components Updated

    • main.tsx: Now uses StackProvider instead of ClerkProvider
    • useAppAuth.ts: Migrated to use Stack Auth hooks
    • SignInPage.tsx and SignUpPage.tsx: Updated to use Stack Auth components
    • NavigationSidebar.tsx: Uses Stack's UserButton component
    • Added StackHandler.tsx for auth flow handling

Backend Changes

  1. Dependencies

    • Added: @stackframe/stack
    • Maintained: @clerk/backend (for backward compatibility)

  2. Authentication Middleware

    • api/middleware/auth.js: Now supports both Clerk and Stack Auth tokens
    • Tries Stack Auth first, falls back to Clerk if needed
    • Seamless transition for existing users

Environment Variables

Frontend (.env)

# Stack Auth Configuration
VITE_STACK_PROJECT_ID=your_stack_project_id
VITE_STACK_PUBLISHABLE_CLIENT_KEY=your_publishable_key

# Backend API
VITE_API_URL=http://localhost:3001

# Optional: Use custom auth forms
VITE_USE_BROWSER_AUTH=false

Backend (.env)

# Stack Auth Configuration
STACK_PROJECT_ID=your_stack_project_id
STACK_SECRET_SERVER_KEY=your_secret_server_key

# Neon Database
DATABASE_URL=postgresql://user:pass@host/db?sslmode=require

# Optional: Clerk (for backward compatibility)
# CLERK_SECRET_KEY=sk_test_...
# CLERK_JWT_KEY=...

Setup Instructions

1. Create Neon Project

  1. Go to neon.tech and create a new project
  2. Copy your database connection string

2. Enable Neon Auth

  1. In the Neon Console, navigate to the Auth section
  2. Enable Neon Auth for your project
  3. Copy the Stack Auth credentials:
    • Project ID
    • Publishable Client Key
    • Secret Server Key

3. Configure Environment

  1. Update frontend .env with Stack Auth credentials
  2. Update backend .env with Stack Auth and database credentials
  3. Remove old Clerk environment variables (unless maintaining backward compatibility)

4. Install Dependencies

# Frontend
cd ai-notes-app
npm install

# Backend
cd ../ai-backend-service
npm install

5. Run the Application

# Start backend
cd ai-backend-service
npm run dev

# Start frontend
cd ../ai-notes-app
npm run dev

Migration Features

Backward Compatibility

  • Backend supports both Clerk and Stack Auth tokens
  • Existing Clerk users can continue to authenticate
  • Gradual migration path available

User Data Sync

  • Neon Auth automatically syncs user data to your database
  • No need for manual user creation or webhooks
  • Real-time updates across all user properties

Enhanced Security

  • JWT tokens with customizable expiration
  • Secure cookie-based token storage
  • Built-in CSRF protection

Benefits of Neon Auth

  1. Unified Platform: Auth and database in one place
  2. Automatic Sync: User data always up-to-date in your database
  3. SQL Queries: Join user data directly with your application data
  4. Performance: Reduced latency with integrated services
  5. Cost Effective: Single billing for auth and database

Troubleshooting

Common Issues

  1. Authentication fails

    • Verify Stack Auth credentials are correct
    • Check that the backend URL is accessible
    • Ensure cookies are enabled in the browser

  2. User data not syncing

    • Check database connection string
    • Verify Neon Auth is enabled in console
    • Look for errors in backend logs

  3. Migration from Clerk

    • Keep Clerk keys during transition period
    • Test with both auth providers
    • Gradually migrate users

Support