Sveltey/docs/AUTHENTICATION_SETUP.md

SvelteKit Supabase Authentication Setup

This project uses Supabase for authentication with full server-side rendering (SSR) support through SvelteKit hooks.

Features

• ✅ Email/Password authentication
• ✅ GitHub OAuth integration
• ✅ Server-side authentication with hooks.server.ts
• ✅ Protected routes with automatic redirects
• ✅ Session management across client and server
• ✅ TypeScript support with proper types

Setup Instructions

1. Environment Variables

Create a .env.local file in your project root:

PUBLIC_SUPABASE_URL=your_supabase_project_url
PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

Get these values from your Supabase project dashboard under Settings > API.

2. Supabase Configuration

Enable GitHub OAuth Provider

1. Go to your Supabase project dashboard
2. Navigate to Authentication > Providers
3. Enable the GitHub provider
4. Add your GitHub OAuth credentials:
   • Client ID: From your GitHub OAuth app
   • Client Secret: From your GitHub OAuth app

GitHub OAuth App Setup

1. Go to GitHub Settings > Developer settings > OAuth Apps
2. Click "New OAuth App"
3. Fill in the details:
   • Application name: Your app name
   • Homepage URL: http://localhost:5173 (for development)
   • Authorization callback URL: https://your-project-ref.supabase.co/auth/v1/callback
4. Note the Client ID and Client Secret for Supabase configuration

3. Supabase Authentication Settings

In your Supabase project settings:

1. Go to Authentication > Settings
2. Add your site URLs:
   • Site URL: http://localhost:5173 (development) / https://yourdomain.com (production)
   • Redirect URLs: Add both your local and production URLs

Architecture Overview

Server-Side Authentication (hooks.server.ts)

The authentication is handled through SvelteKit hooks:

// src/hooks.server.ts
export const handle: Handle = sequence(supabase, authGuard);

Features:

• supabase hook: Creates server-side Supabase client with cookie management
• authGuard hook: Protects routes and handles redirects
• Session validation: Validates JWTs on every request
• Cookie management: Automatic token refresh and cookie handling

Protected Routes

Routes are automatically protected based on path patterns:

• /dashboard/*: Requires authentication, redirects to /auth/login if not authenticated
• /auth/*: Redirects authenticated users to /dashboard

Client-Side Integration (+layout.svelte)

The root layout handles client-side authentication state:

// Syncs server-side session with client-side
$effect(() => {
    session = data.session;
});

// Handles auth state changes
supabase.auth.onAuthStateChange((event, newSession) => {
    if (newSession?.expires_at !== session?.expires_at) {
        invalidateAll();
    }
});

File Structure

src/
├── hooks.server.ts              # Server-side authentication hooks
├── app.d.ts                     # TypeScript definitions for Supabase
├── lib/
│   ├── index.ts                # Exports (toaster)
│   └── supabaseClient.ts       # Browser Supabase client
├── routes/
│   ├── +layout.svelte          # Root layout with auth state
│   ├── +layout.server.ts       # Server layout with session data
│   ├── auth/
│   │   ├── login/+page.svelte  # Login page with GitHub OAuth
│   │   ├── signup/+page.svelte # Signup page with GitHub OAuth  
│   │   └── logout/+page.server.ts # Logout action
│   └── dashboard/
│       ├── +layout.server.ts   # Dashboard layout (protected)
│       └── +page.svelte        # Dashboard page

Usage Examples

Login Page Features

• Email/password authentication
• GitHub OAuth login
• Form validation and error handling
• Loading states
• Automatic redirect after login

Signup Page Features

• Email/password registration
• GitHub OAuth signup
• Email confirmation handling
• Error handling with toast notifications

Dashboard Protection

The dashboard is automatically protected and will:

• Redirect unauthenticated users to login
• Display user information for authenticated users
• Handle session expiration gracefully

TypeScript Support

Full TypeScript support with proper types:

// app.d.ts
interface Locals {
    supabase: SupabaseClient;
    safeGetSession(): Promise<{ session: Session | null; user: User | null }>;
    session: Session | null;
    user: User | null;
}

Development

1. Start your development server:

npm run dev

2. Test authentication:
   • Visit /auth/signup to create an account
   • Try GitHub OAuth login
   • Visit /dashboard to see protected content
   • Test logout functionality

Security Features

• JWT validation: Server-side validation of authentication tokens
• Automatic refresh: Tokens are refreshed automatically
• Secure cookies: HTTP-only cookies for session management
• Route protection: Server-side route guards
• CSRF protection: Built into Supabase auth flow

Troubleshooting

Common Issues

1. "Cannot redirect during render": Usually caused by trying to redirect in a load function without throwing the redirect
2. OAuth callback errors: Check your GitHub OAuth app callback URL matches Supabase settings
3. Session not persisting: Ensure cookies are configured correctly in hooks.server.ts

Debug Tips

• Check browser Network tab for auth requests
• Verify Supabase project settings match your configuration
• Test OAuth flow in incognito mode to avoid cached sessions