I Spent a Weekend Integrating Clerk + Supabase + Next.js (So You Don't Have To)

Look, I tried building auth myself. Twice. First time took three weeks and still had security holes you could drive a truck through. Second time I used NextAuth and spent more time fighting with session management than building features.

Then I discovered this combination: Clerk for the auth headache, Supabase for the database (with Row-Level Security that actually works), and Next.js 15 to tie it all together. It's not perfect, but it's the least painful way I've found to get production-ready authentication.

The Real Problem with Auth

Here's the thing nobody tells you: authentication isn't just "check if user is logged in." You need:

• Sign up/sign in flows that don't suck
• Password reset that actually works
• Social login (because users expect it)
• Session management that handles edge cases
• Database security so users can't see each other's data
• Token refresh that doesn't break your app

Building this yourself means months of work and constant security patches. The OWASP Auth Cheat Sheet lists 50+ security considerations you need to handle. Using separate services means integration hell, but at least you're not implementing OAuth from scratch and dealing with PKCE flows.

How The Pieces Actually Work Together

Here's what happens when a user signs in (and where it breaks):

1. Clerk handles the auth dance - User clicks sign in, Clerk shows the modal, handles OAuth with Google/GitHub, validates everything
2. JWT tokens get passed around - Clerk issues a JWT token with the user ID in the sub claim
3. Supabase verifies the token - Using Clerk's JWKS endpoint and JWT verification (this took me forever to configure right)
4. Row-Level Security kicks in - Supabase automatically filters queries based on `requesting_user_id()` function and PostgreSQL RLS policies
5. Next.js does the plumbing - Server Components get auth state, Client Components get real-time data via Supabase Realtime

The part that'll bite you: token refresh happens silently, but if your Supabase client isn't configured right, you'll get random 401s that are hell to debug.

Why I Actually Use This Stack

Clerk's UI components don't suck: Their sign-in modal looks professional out of the box. Compare that to building your own forms with form validation, error handling, and accessibility compliance - you'll spend weeks getting it right.

Supabase RLS is bulletproof: Once you set up Row-Level Security policies correctly using PostgreSQL's native RLS, users literally cannot access each other's data. Even if they figure out your API endpoints and try direct database queries.

Next.js 15 App Router plays nice: The App Router architecture with Server Actions and Middleware handles auth state cleanly. No more wrestling with cookies or session storage.

It scales without thinking: I've deployed this pattern on apps with 50K+ users - Clerk handles the auth load, Supabase handles the database queries, Vercel handles the Next.js hosting.

The pain points: Clerk gets expensive fast ($25 base + $0.02 per MAU after 10k), Supabase's free tier is generous but you'll hit database limits if you're not careful, and debugging JWT issues means understanding three different systems when shit breaks.

Worth it? Hell yes. This integration saved me probably 6 weeks of building auth from scratch, and I haven't had a single security incident in production since implementing it.

Alright, time for the actual implementation. I'm going to save you the 6 hours I spent figuring out why my JWT tokens weren't working and why my RLS policies were letting users see each other's data.

Step 1: Clerk Configuration (The Part That's Actually Easy)

Go to your Clerk dashboard and create a new application. The setup wizard is actually decent - follow it.

Critical step everyone misses: As of April 1, 2025, the old Clerk JWT template method is deprecated. Use the new native third-party auth integration instead.

Setup steps:

1. In your Clerk dashboard, go to Supabase integration setup
2. Click "Activate Supabase integration" and copy your Clerk domain
3. In Supabase dashboard, go to Authentication → Sign In/Up → Third Party Auth
4. Click "Add provider", select Clerk, paste your Clerk domain

That's it. No more wrestling with JWT templates and JWKS endpoints. The new integration handles token verification automatically.

Step 2: Supabase Database Setup (Where Things Get Tricky)

Here's the SQL you actually need. The official docs are confusing, and the PostgreSQL documentation is overwhelming. Even Supabase's RLS examples don't cover this integration pattern. Here's the working version that handles Clerk's JWT format with Supabase's auth helpers:

-- First, create the function that extracts user ID from Clerk tokens
-- Using the new auth.jwt() method for third-party providers
CREATE OR REPLACE FUNCTION requesting_user_id()
RETURNS TEXT AS $$
  SELECT NULLIF(
    (auth.jwt() ->> 'sub')::text,
    ''
  );
$$ LANGUAGE SQL STABLE;

-- Example table with proper RLS setup
CREATE TABLE posts (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id TEXT NOT NULL DEFAULT requesting_user_id(),
  title TEXT NOT NULL,
  content TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Enable RLS (this line is CRITICAL - forget it and users see everything)
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

-- Create the policy that actually works
CREATE POLICY "Users can manage their own posts"
  ON posts
  FOR ALL
  USING (requesting_user_id() = user_id)
  WITH CHECK (requesting_user_id() = user_id);

Gotcha that cost me 2 hours: If you forget the WITH CHECK clause, users can create posts but then can't read them back. Stack Overflow thread with 100+ people hitting the same issue. This happens because PostgreSQL RLS treats USING (for SELECT) and WITH CHECK (for INSERT/UPDATE) as separate conditions. The Supabase RLS cookbook doesn't make this clear enough.

Step 3: Next.js Integration (The Painful Part)

This is where I wasted most of my time. The Next.js 15 App Router changed how authentication middleware works, and Clerk's Next.js guide doesn't cover all the edge cases. The Supabase Next.js auth helpers assume you're using Supabase Auth, not an external JWT provider. Here's what actually works after reading through GitHub issues and Discord discussions:

// lib/supabase.ts
'use client';

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

export function useSupabaseClient() {
  const { session } = useSession();
  
  return createClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      // With native integration, session token works directly
      accessToken: async () => {
        if (!session) return null;
        return await session.getToken();
      },
    }
  );
}

Server-side version for Server Components:

// lib/supabase-server.ts
import { createClient } from '@supabase/supabase-js';
import { auth } from '@clerk/nextjs/server';

export async function createSupabaseServerClient() {
  const { getToken } = auth();
  
  return createClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      accessToken: async () => {
        return await getToken();
      },
    }
  );
}

What WILL Break (And How to Debug It)

Random 401 errors: Your third-party auth provider setup isn't right, or you're hitting Clerk's token refresh timing. Check Clerk's debugging guide and verify your Clerk domain is correctly set in Supabase.

Users seeing each other's data: You forgot to enable RLS or your policy syntax is wrong. This is the most dangerous bug - I've seen it in production twice. Test this in the Supabase SQL editor using RLS testing techniques:

-- Test your RLS policy with Clerk user ID
-- Note: You'll need to use an actual Clerk user ID for testing
SELECT auth.jwt() ->> 'sub' as current_user_id;
SELECT * FROM posts; -- Should only return posts for the authenticated user

Token refresh issues: Clerk v5 changed the session API. Make sure you're using session.getToken() not the old session.sessionToken.

CORS errors in development: Add http://localhost:3000 to your Clerk dashboard allowed origins. Production? Add your actual domain.

Production Horror Stories

The time RLS wasn't enabled: Deployed to production, users could see everyone's data for 6 hours before I caught it. Always test your policies in staging first.

The JWT token refresh loop: Clerk's webhook retry logic overwhelmed our API during a brief outage. Implement exponential backoff in your webhook handlers.

The 20-second loading states: JWT token refresh was happening on every page load. Fixed by properly configuring React Query's stale time.

Budget 2-3 days for this integration if you're doing it for the first time. The docs make it sound like 30 minutes - it's fucking not.

But once it works? You've got bulletproof auth that scales, database security that actually works, and UI components that don't look like they were designed by a backend engineer. It's the closest thing to "set it and forget it" authentication I've found.