Install and configure the Supabase client

npm install @supabase/supabase-js

Create a Supabase client file (lib/supabase.ts):

import { createClient } from '@supabase/supabase-js';

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!;
const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!;

export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
  auth: {
    autoRefreshToken: true,
    persistSession: true,
    detectSessionInUrl: true,
    flowType: 'pkce'  // More secure for SPAs
  }
});

// WRONG: Service role key on client exposes full database access
const supabase = createClient(url, process.env.SUPABASE_SERVICE_ROLE_KEY);

Configure auth settings in Supabase Dashboard

Go to Authentication > URL Configuration and set:

• Site URL: Your production URL (e.g., https://myapp.com)
• Redirect URLs: Add all valid redirect destinations

# Add these redirect URLs:
http://localhost:3000/**
https://myapp.com/**
https://staging.myapp.com/**

In Authentication > Settings, configure:

• Enable email confirmations for production
• Set secure password requirements (min 8 chars)
• Configure session lifetime (default 1 week)

Implement secure sign-up and sign-in

// Sign up with email and password
async function signUp(email: string, password: string) {
  const { data, error } = await supabase.auth.signUp({
    email,
    password,
    options: {
      emailRedirectTo: `${window.location.origin}/auth/callback`,
      data: {
        // Optional: Add user metadata
        display_name: 'New User'
      }
    }
  });

  if (error) {
    // Handle specific errors
    if (error.message.includes('already registered')) {
      throw new Error('An account with this email already exists');
    }
    throw error;
  }

  return data;
}

// Sign in with email and password
async function signIn(email: string, password: string) {
  const { data, error } = await supabase.auth.signInWithPassword({
    email,
    password
  });

  if (error) {
    // Don't reveal whether email exists
    throw new Error('Invalid email or password');
  }

  return data;
}

// Sign out
async function signOut() {
  const { error } = await supabase.auth.signOut();
  if (error) throw error;
}

Handle session state properly

import { useEffect, useState } from 'react';
import { Session, User } from '@supabase/supabase-js';
import { supabase } from '@/lib/supabase';

export function useAuth() {
  const [user, setUser] = useState<User | null>(null);
  const [session, setSession] = useState<Session | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    // Get initial session
    supabase.auth.getSession().then(({ data: { session } }) => {
      setSession(session);
      setUser(session?.user ?? null);
      setLoading(false);
    });

    // Listen for auth changes
    const { data: { subscription } } = supabase.auth.onAuthStateChange(
      async (event, session) => {
        setSession(session);
        setUser(session?.user ?? null);

        // Handle specific events
        if (event === 'SIGNED_OUT') {
          // Clear any cached data
        }
        if (event === 'TOKEN_REFRESHED') {
          // Session was refreshed
        }
        if (event === 'USER_UPDATED') {
          // User data changed
        }
      }
    );

    return () => subscription.unsubscribe();
  }, []);

  return { user, session, loading };
}

Create auth callback handler

For the PKCE flow, create an auth callback page (app/auth/callback/route.ts for Next.js App Router):

import { createRouteHandlerClient } from '@supabase/auth-helpers-nextjs';
import { cookies } from 'next/headers';
import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  const requestUrl = new URL(request.url);
  const code = requestUrl.searchParams.get('code');
  const next = requestUrl.searchParams.get('next') ?? '/dashboard';

  if (code) {
    const supabase = createRouteHandlerClient({ cookies });

    // Exchange code for session
    const { error } = await supabase.auth.exchangeCodeForSession(code);

    if (!error) {
      return NextResponse.redirect(new URL(next, requestUrl.origin));
    }
  }

  // Redirect to error page if code exchange fails
  return NextResponse.redirect(
    new URL('/auth/error?message=Could not authenticate', requestUrl.origin)
  );
}

Integrate auth with Row Level Security

Create RLS policies that use auth.uid():

-- Enable RLS on your table
ALTER TABLE user_profiles ENABLE ROW LEVEL SECURITY;

-- Policy: Users can only read their own profile
CREATE POLICY "Users can view own profile"
ON user_profiles FOR SELECT
USING (auth.uid() = id);

-- Policy: Users can update their own profile
CREATE POLICY "Users can update own profile"
ON user_profiles FOR UPDATE
USING (auth.uid() = id);

-- Policy: Auto-create profile on signup (via trigger)
CREATE OR REPLACE FUNCTION public.handle_new_user()
RETURNS trigger AS $$
BEGIN
  INSERT INTO public.user_profiles (id, email, created_at)
  VALUES (new.id, new.email, now());
  RETURN new;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

CREATE TRIGGER on_auth_user_created
  AFTER INSERT ON auth.users
  FOR EACH ROW EXECUTE FUNCTION public.handle_new_user();

Now your queries automatically filter by user:

// This only returns the current user's data (thanks to RLS)
const { data, error } = await supabase
  .from('user_profiles')
  .select('*')
  .single();

Set up social authentication providers

In Supabase Dashboard, go to Authentication > Providers and enable Google:

1. Create OAuth credentials in Google Cloud Console
2. Add authorized redirect URI: https://[your-project].supabase.co/auth/v1/callback
3. Enter Client ID and Secret in Supabase

// Sign in with Google
async function signInWithGoogle() {
  const { data, error } = await supabase.auth.signInWithOAuth({
    provider: 'google',
    options: {
      redirectTo: `${window.location.origin}/auth/callback`,
      queryParams: {
        access_type: 'offline',
        prompt: 'consent'
      }
    }
  });

  if (error) throw error;
}

// Sign in with GitHub
async function signInWithGitHub() {
  const { data, error } = await supabase.auth.signInWithOAuth({
    provider: 'github',
    options: {
      redirectTo: `${window.location.origin}/auth/callback`,
      scopes: 'read:user user:email'
    }
  });

  if (error) throw error;
}

Verify sessions server-side for sensitive operations

For API routes or server components, always verify the session:

// Next.js API Route (Pages Router)
import { createPagesServerClient } from '@supabase/auth-helpers-nextjs';

export default async function handler(req, res) {
  const supabase = createPagesServerClient({ req, res });

  // Get and verify session
  const { data: { session }, error } = await supabase.auth.getSession();

  if (!session) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // User is authenticated - session.user contains user data
  const userId = session.user.id;

  // Perform authorized action...
  const { data } = await supabase
    .from('sensitive_data')
    .select('*')
    .eq('user_id', userId);

  return res.json(data);
}

// Next.js Server Component (App Router)
import { createServerComponentClient } from '@supabase/auth-helpers-nextjs';
import { cookies } from 'next/headers';
import { redirect } from 'next/navigation';

export default async function ProtectedPage() {
  const supabase = createServerComponentClient({ cookies });
  const { data: { session } } = await supabase.auth.getSession();

  if (!session) {
    redirect('/login');
  }

  return <div>Welcome, {session.user.email}</div>;
}