{ "componentChunkName": "component---src-pages-blog-markdown-remark-fields-slug-js", "path": "/blog/how-to-integrate-clerk-with-supabase", "result": {"data":{"markdownRemark":{"html":"

In this guide, we’ll walk through integrating Clerk with Supabase step-by-step. We start with a basic, no-auth Next.js app and gradually add authentication and secure, user-specific data storage using Clerk for auth and Supabase for data. You’ll end up with a diagram editor where each user can save and retrieve their own diagrams.

\n

What You’ll Learn

\n\n

We begin with a simple “no-auth” editor (users can draw and preview Mermaid diagrams, but nothing is saved). Then we layer on Clerk and Supabase. Clerk provides sign-in flows, session tokens, and user IDs. Supabase holds the diagrams and enforces per-user data access via RLS.

\n

Finally, we’ll introduce SuperTokens as an alternative in Part II, showing how it can offer more control (especially for session management) while still working with Supabase. Clerk is great out of the box if you want a quick, managed solution, but SuperTokens is worth a look if you need advanced extensibility or self-hosting.

\n

How Clerk and Supabase Work Together

\n

In this integration, Clerk and Supabase take on two distinct roles:

\n\n

How the Integration Flow Works

\n
    \n
  1. User signs in with Clerk
    Clerk verifies their credentials and returns a JWT (JSON Web Token) containing the user’s unique ID (sub claim).
    2. \n
  2. Your app sends the JWT to Supabase
    You configure the Supabase client to include Clerk’s token on each request. Supabase sees the token and uses it to identify the user.
    3. \n
  3. Supabase enforces RLS policies
    For example, if we have a charts table with a user_id column, RLS policies can be written like:\n\n \n \n \n \n
    -- Only allow a user to see rows where user_id matches their ID from Clerk\npolicy \"Users can access their own charts\"\non charts\nfor all\nusing (auth.uid() = user_id);
    \n
    4. \n
\n
\n

RLS ensures each user sees only their own data, even in a shared database.

\n
\n

This works because

\n\n

Clerk and Supabase Integration: Project Overview

\n

🐙 View the full demo on GitHub - this Next.js example shows Clerk + Supabase in action.

\n

App Features:

\n\n

Initial State: The app starts as a simple, stateless editor. Users can draw and preview diagrams, but nothing is saved – as soon as the page reloads, the content is lost.

\n

With Clerk + Supabase: After adding Clerk, users must sign in. Then, with Supabase connected, each user can save their diagram, and it will reappear the next time they log in. Each saved chart is tagged with that user’s Clerk user ID, and RLS guarantees no user can see another’s charts. This turns the tool into a full multi-user app with persistent, private data.

\n

What You’ll Build

\n

We’ll enhance the basic editor by adding:

\n
    \n
  1. Clerk Authentication: Add Clerk to the Next.js app. Users can sign up and sign in (or sign out). After login, they see personalized content.
    2. \n
  2. Supabase Integration: Configure Supabase so that each signed-in user can save their diagrams to the database. Supabase will use the Clerk user ID (from the JWT) to scope the data. RLS policies enforce that users only access their own data.
    3. \n
\n

By the end, you’ll have a working diagram editor where each user signs in, sees their own saved charts, and nothing else.

\n

\n \n \n \n \n \n \n

# If you're using npm \nnpm install @clerk/nextjs\n\n# If you're using yarn \nyarn add @clerk/nextjs\n\n# If you're using pnpm\npnpm add @clerk/nextjs
\n

This SDK gives you React components (like SignInButton) and server helpers for middleware.

\n

4. Set your Clerk API keys

\n

Add these keys to your .env file, or create the file if it doesn’t exist.

\n\n \n \n \n \n
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your-clerk-key\nCLERK_SECRET_KEY=your-clerk-secret
\n

5. Update middleware.ts

\n

Update your middleware file, or create one at the root of your project, or the src/ directory if you’re using a src/ directory structure.

\n

The clerkMiddleware helper enables authentication and is where you’ll configure your protected routes.

\n\n \n \n \n \n
import { clerkMiddleware } from \"@clerk/nextjs/server\";\n\nexport default clerkMiddleware();\n\nexport const config = {\n  matcher: [\n    // Skip Next.js internals and all static files, unless found in search params\n    '/((?!_next|[^?]*\\\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',\n    // Always run for API routes\n    '/(api|trpc)(.*)',\n  ],\n};
\n

6. Add ClerkProvider and the SignUp/SignIn Buttons

\n

To enable Clerk throughout your app, you’ll use the ClerkProvider in your layout.tsx file.

\n

Here’s what to do:

\n
    \n
  • Import the necessary components from @clerk/nextjs.
    • \n
  • Wrap your app with ClerkProvider to make Clerk’s features available globally.
    • \n
  • Use SignedOut to wrap the SignInButton andSignUpButton. These will only appear when the user is signed out.
    • \n
  • Use SignedIn to wrap both the UserButton and your app’s content. These will only show when the user is signed in.
    • \n
\n) {\n return (\n // ✅ ClerkProvider wraps the entire app, enabling access to auth state and Clerk components\n \n \n \n
\n\n {/* 👋 Show these only when the user is signed out */}\n \n {/* Opens a modal for users to sign in */}\n {/* Opens a modal for users to create an account */}\n \n\n {/* 🙌 Show these only when the user is signed in */}\n \n {/* Shows user profile options like sign out */}\n {children} {/* Show the app content only to signed-in users */}\n \n \n
\n \n \n \n );\n}`, `33080198856391150000`)\"\n >\n \n \n \n \n
import { type Metadata } from \"next\";\nimport { Geist, Geist_Mono } from \"next/font/google\";\nimport \"./globals.css\";\n// 🔐 Clerk components for authentication flowsimport {  ClerkProvider, // Wraps your app to provide authentication context  SignInButton, // Renders a sign-in button that opens Clerk's sign-in modal  SignUpButton, // Renders a sign-up button that opens Clerk's sign-up modal  SignedIn, // Conditionally renders children *only* if the user is signed in  SignedOut, // Conditionally renders children *only* if the user is signed out  UserButton, // Displays the user's avatar with a dropdown for account management} from '@clerk/nextjs'\nconst geistSans = Geist({\n  variable: \"--font-geist-sans\",\n  subsets: [\"latin\"],\n});\n\nconst geistMono = Geist_Mono({\n  variable: \"--font-geist-mono\",\n  subsets: [\"latin\"],\n});\n\nexport const metadata: Metadata = {\n  title: \"Create Next App\",\n  description: \"Generated by create next app\",\n};\n\nexport default function RootLayout({\n  children,\n}: Readonly<{\n  children: React.ReactNode;\n}>) {\n  return (\n    // ✅ ClerkProvider wraps the entire app, enabling access to auth state and Clerk components\n    <ClerkProvider>      <html lang=\"en\">\n        <body className={`${geistSans.variable} ${geistMono.variable} antialiased`} >\n          <header className=\"p-5\">\n\n          {/* 👋 Show these only when the user is signed out */}          <SignedOut>            <SignInButton /> {/* Opens a modal for users to sign in */}            <SignUpButton /> {/* Opens a modal for users to create an account */}          </SignedOut>\n          {/* 🙌 Show these only when the user is signed in */}          <SignedIn>            <UserButton /> {/* Shows user profile options like sign out */}            {children}  {/* Show the app content only to signed-in users */}          </SignedIn>          \n        </header>\n        </body>\n      </html>\n    </ClerkProvider>  );\n}
\n

🎉 And that’s it! You’ve now set up Clerk for user authentication in your app. Users can sign in, sign up, and see personalized content based on their auth state.

\n

7. Run Your Project and Get Your First User

\n

Start your dev server:

\n\n \n \n \n \n
# If you're using npm \nnpm run dev\n\n# If you're using yarn \nyarn dev\n\n# If you're using pnpm\npnpm dev
\n

Once it’s running, head to http://localhost:3000 in your browser. You should see your app with sign-in and sign-up options. Go ahead and register—this will create your first authenticated user.

\n

Next up, we’ll connect Supabase and set it up to store user-specific data like saved Mermaid charts.

\n

Setting Up Supabase with Clerk

\n

To integrate Supabase with your Next.js project and secure user-specific data using Clerk authentication, follow these steps:

\n

1. Create a Supabase Project

\n
    \n
  • Visit supabase.com and sign up for a free account.
    • \n
  • Once inside the dashboard, click “New Project”.
    • \n
  • Choose a Project Name (e.g. Mermaid Visualizer), select the closest region for your users, and set a strong password (you can use the “Generate Password” feature).
    • \n
  • Save this password in your password manager.
    • \n
\n

2. Install Supabase Client

\n

Install the Supabase JavaScript client in your project:

\n\n \n \n \n \n
npm install @supabase/supabase-js
\n

3. Connect Clerk to Supabase (New 2025 Flow)

\n

As of April 2025, Supabase has updated its integration method with Clerk from JWT templates to native third-party support, which simplifies setup and improves security.

\n
    \n
  1. Configure Clerk for Supabase: In your Clerk dashboard, navigate to API Keys and enable Supabase compatibility.
    2. \n
  2. Add Clerk as a Third-Party Auth Provider in Supabase: In Supabase, go to Authentication > Providers > External OAuth and select Clerk. You’ll need to input the Issuer URL and JWKS endpoint from Clerk (Clerk’s docs or connect page will show you what values to use).
    3. \n
\n

4. Set Up Row-Level Security (RLS) with Clerk

\n

By default, Supabase uses its own auth.uid() method, which doesn’t work when using Clerk. To fix that, we’ll extract the authenticated user’s ID from the Clerk-provided JWT.

\n

Create a Helper Function for Clerk IDs

\n

In Supabase’s SQL Editor, paste the following:

\n>'sub',\n ''\n )::text;\n\\$\\$ LANGUAGE SQL STABLE;`, `95280324012653380000`)\"\n >\n \n \n \n \n
CREATE OR REPLACE FUNCTION requesting_user_id()\nRETURNS TEXT AS $$\n  SELECT NULLIF(\n    current_setting('request.jwt.claims', true)::json->>'sub',\n    ''\n  )::text;\n$$ LANGUAGE SQL STABLE;
\n

This function safely retrieves the authenticated Clerk user ID from the incoming JWT token.

\n

Create the charts Table

\n

Run the following SQL to create a table and enable RLS with Clerk support:

\n\n \n \n \n \n
create table if not exists charts (\n  id UUID default gen_random_uuid() primary key,\n  content text not null,\n  user_id text not null,\n  created_at timestamptz default now()\n);
\n

Add RLS Policies (the Right Way for Clerk)

\n>'sub'\n );\n\ncreate policy "Users can view their own charts"\n on charts\n for select\n using (\n user_id = current_setting('request.jwt.claims', true)::json->>'sub'\n );`, `87742739946475180000`)\"\n >\n \n \n \n \n
alter table charts enable row level security;\n\ncreate policy \"Users can insert their own charts\"\n  on charts\n  for insert\n  with check (\n    user_id = current_setting('request.jwt.claims', true)::json->>'sub'\n  );\n\ncreate policy \"Users can view their own charts\"\n  on charts\n  for select\n  using (\n    user_id = current_setting('request.jwt.claims', true)::json->>'sub'\n  );
\n

Common Pitfall: auth.uid() Returns NULL

\n

If you previously used this:

\n\n \n \n \n \n
USING (auth.uid()::text = user_id)
\n

…it won’t work with Clerk. Why?

\n
    \n
  • auth.uid() is only available if you’re using Supabase Auth, which we’re not.
    • \n
  • Clerk user IDs are strings like \"user_2w2a6PJC4T4BfXDsg72AQsLNEyU\", which are not UUIDs.
    • \n
  • This mismatch causes errors like:\n\n \n \n \n \n
    invalid input syntax for type uuid: \"user_...\"
    \n
    • \n
\n

The Fix:\nUse this pattern instead:

\n>'sub'`, `89631604091959000000`)\"\n >\n \n \n \n \n
current_setting('request.jwt.claims', true)::json->>'sub'
\n

This safely extracts the sub field (i.e. the Clerk user ID) from the JWT, allowing you to scope data per user, securely and correctly.

\n

Integrating Clerk and Supabase in Next.js

\n

Clerk and Supabase work together seamlessly to manage authentication and user-specific data in your Next.js app. Here’s how the integration functions:

\n
    \n
  1. Authentication with Clerk: When a user logs in, Clerk authenticates them and generates a unique user ID and session token.
    2. \n
  2. Data Storage with Supabase: That user ID is used to store and retrieve data (e.g. Mermaid charts) in the Supabase database, scoped to the logged-in user.
    3. \n
\n

Let’s break down how to implement this integration in code:

\n

Middleware for Clerk Authentication

\n

The middleware.ts file ensures that all routes requiring authentication are protected by Clerk. It intercepts requests and verifies the session before allowing access:

\n\n \n \n \n \n
import { clerkMiddleware } from \"@clerk/nextjs/server\";\n\nexport default clerkMiddleware();\n\nexport const config = {\n  matcher: [\n    '/((?!_next|[^?]*\\\\.(?:html?|css|js|png|svg)).*)',\n    '/(api|trpc)(.*)',\n  ],\n};
\n

Supabase Provider with Clerk Session Token

\n

In order to securely access Supabase on behalf of the authenticated user, we initialize a Supabase client using the session token provided by Clerk:

\n session?.getToken() \n }\n );\n\n return {children};\n}`, `12104934275918412000`)\"\n >\n \n \n \n \n
import { createClient } from \"@supabase/supabase-js\";\nimport { useSession } from \"@clerk/nextjs\";\n\nexport default function SupabaseProvider({ children }: { children: React.ReactNode }) {\n  const { session } = useSession();\n  const supabase = createClient(\n    process.env.NEXT_PUBLIC_SUPABASE_URL!,\n    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!, { \n      accessToken: () => session?.getToken() \n    }\n  );\n\n  return <Context.Provider value={{ supabase }}>{children}</Context.Provider>;\n}
\n

Code Walkthrough

\n

You can explore the full codebase in the GitHub repository.

\n

Saving Charts

\n

The handleSave function stores a Mermaid chart in your Supabase database, associating it with the currently logged-in user:

\n {\n if (!supabase || !user) return;\n\n const { data, error } = await supabase\n .from('charts')\n .insert({ content: code, user_id: user.id });\n\n if (error) console.error('Error saving chart:', error);\n};`, `18049940067534154000`)\"\n >\n \n \n \n \n
const handleSave = async () => {\n  if (!supabase || !user) return;\n\n  const { data, error } = await supabase\n    .from('charts')\n    .insert({ content: code, user_id: user.id });\n\n  if (error) console.error('Error saving chart:', error);\n};
\n

Fetching Charts

\n

The fetchCharts function retrieves all charts for the authenticated user, ordered by creation time:

\n {\n const { data, error } = await supabase\n .from('charts')\n .select('content')\n .order('created_at', { ascending: false });\n\n if (data) setSavedCharts(data.map((item) => item.content));\n};`, `9237076688014901000`)\"\n >\n \n \n \n \n
const fetchCharts = async () => {\n  const { data, error } = await supabase\n    .from('charts')\n    .select('content')\n    .order('created_at', { ascending: false });\n\n  if (data) setSavedCharts(data.map((item) => item.content));\n};
\n

Challenges and Solutions

\n
    \n
  • Session Management:
    Challenge: Ensure Clerk’s session is available before initializing Supabase.
    Solution: Use useEffect to wait for the session before creating the Supabase client.
    • \n
  • Error Handling:
    Challenge: Errors when saving or fetching data can disrupt the UX.
    Solution: Implement error checks and show clear feedback to the user.
    • \n
\n

What About Session Security? (The Hidden Risk No One Talks About)

\n

So far, Clerk + Supabase covers authentication (who the user is) and data access rules. But one aspect often overlooked is session security. Common risks include:

\n
    \n
  • Stolen Tokens: If an attacker somehow obtains a user’s refresh token or access token (via XSS, device theft, etc.), they can impersonate that user until the token expires.
    • \n
  • Replay Attacks: Without proper handling, someone could reuse an old valid refresh token to continue a session indefinitely.
    • \n
  • Session Hijacking: If your system only allows a single session per user, an attacker who logs in on one device can knock out other sessions, and vice versa.
    • \n
\n

Clerk and Supabase handle basic sessions well (Clerk rotates refresh tokens, etc.), but these advanced threats can still be concerns. This is where SuperTokens shines. It’s designed with advanced session security features.

\n

How SuperTokens Fixes This Problem

\n

SuperTokens puts session security at the forefront. Compared to Clerk or vanilla Supabase Auth, SuperTokens offers:

\n
    \n
  • Self-hosted & fully customizable: You can self-host SuperTokens (or use the cloud hosting option). Because it’s open source, you have full control. This means you aren’t locked into a vendor.
    • \n
  • Advanced session management: Out of the box, SuperTokens uses short-lived access tokens and rotating refresh tokens. Each time a refresh token is used, a new one is issued and the old one is invalidated. This one-time-use refresh scheme means a stolen refresh token is useless after first use.
    • \n
  • Token theft detection & rotation: SuperTokens can detect if a refresh token is being reused (an anomaly indicating theft) and revoke all sessions for that user immediately.
    • \n
  • Granular session revocation: You can revoke individual device sessions. For instance, SuperTokens provides backend functions like Session.revokeSession(sessionHandle) or Session.revokeAllSessionsForUser(userId), letting you target a specific session or wipe all of a user’s sessions.
    • \n
\n

These features directly mitigate the risks above:

\n
    \n
  • Stolen token → short expiry & rotation: Even if an access token is stolen, it will expire quickly. If a refresh token is stolen, SuperTokens will notice its reuse and invalidate it, limiting damage to minutes.
    • \n
  • Replay attacks → token rotation: Reusing a refresh token triggers detection. The user’s session can be revoked immediately, so replayed tokens get caught.
    • \n
  • Hijacking → per-device logout: Users can log out of one device without logging out everywhere, since sessions are separate. An attacker in one session can be locked out while others stay intact.
    • \n
\n

By design, SuperTokens “belongs in the backend” of your auth flow. You can still use Clerk’s or your own front end if you wish, but swap in SuperTokens on the server to handle sessions. In short, SuperTokens fixes session management in a way many providers don’t.

\n

How SuperTokens Handles Session Security (In Practice)

\n

Here’s a quick comparison of how these threats are handled:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ThreatRisk Without ProtectionSuperTokens Defense
Token TheftAttacker reuses a stolen refresh token indefinitely.Short-lived access tokens + rotating refresh tokens. If a refresh token is stolen and reused, SuperTokens detects the anomaly and revokes it.
Session HijackingLogging out all devices if a user is compromised on one.Per-session tokens: SuperTokens lets you revoke a single session handle (device) or all sessions for a user, avoiding a blanket logout.
Replay AttacksA stolen refresh token could be saved and replayed.Refresh tokens are one-time-use. Reuse triggers detection; old tokens are invalidated.
\n

Learn more about how SuperTokens handles these threats.

\n

Clerk vs. Supabase vs. SuperTokens

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FeatureClerk 🧰Supabase 🗄️SuperTokens 🛡️
Pre-Built UI Components✅ Yes❌ No✅ Yes (optional)
Custom Auth Flows⚠️ Limited⚠️ Limited✅ Full flexibility
Session Management⚠️ Basic⚠️ Basic✅ Advanced
Self-Hosting❌ No✅ Yes (via CLI)✅ Yes
Token Theft Detection❌ No❌ No✅ Yes
Fine-Grained Session Revocation❌ No❌ No✅ Yes
\n
    \n
  • Pre-Built UI: Clerk and SuperTokens both offer ready-made login/signup UI components. Supabase itself does not include UI (it’s just a backend service). For example, SuperTokens’ docs explicitly mention using their pre-built UI components (or you can choose a custom UI).
    • \n
  • Custom Flows: Clerk allows some configuration, but SuperTokens lets you override everything. You can inject your own logic into any part of the auth flow.
    • \n
  • Session Security: Clerk and Supabase provide basic session handling, but SuperTokens is designed for security. As discussed above, it offers rotating tokens, theft detection, and per-session revocation.
    • \n
  • Self-Hosting: Supabase is open-source so you can self-host it via the Supabase CLI or Cloud.
    • \n
\n

In short, SuperTokens stands out for its flexibility and security. It gives devs full control over auth logic and sessions without sacrificing convenience (it also has pre-built UIs and a simple integration).

\n

Custom Auth Flows with SuperTokens

\n

SuperTokens lets you override every piece of the logic—perfect for apps with unique flows or compliance requirements.

\n

Example: Add custom sign-in behavior:

\n ({\n ...original,\n signInUp: async (input) => {\n // Custom logic here\n }\n })\n}`, `68327016731654136000`)\"\n >\n \n \n \n \n
override: {\n  functions: (original) => ({\n    ...original,\n    signInUp: async (input) => {\n      // Custom logic here\n    }\n  })\n}
\n

You can also build your own UI, or start with theirs and customize as needed.

\n\n

Should You Use Clerk, SuperTokens, or Both?

\n

There’s no one-size-fits-all answer, but here are some guidelines:

\n
    \n
  • Choose Clerk if you want a fully managed auth solution with beautiful, drop-in UI components and minimal setup. Clerk covers most common use cases out of the box.
    • \n
  • Choose SuperTokens if you need ultimate control over auth and sessions. For example, if you must self-host, enforce custom token lifetimes, or build a very custom workflow, SuperTokens gives you that flexibility.
    • \n
  • Use Both in a hybrid approach. You might love Clerk’s React components and user experience, but still want SuperTokens’ session security. You can start with Clerk handling UI and signup, and then integrate SuperTokens behind the scenes for session issuance (or vice versa). SuperTokens even provides migration guides from other systems, so you can gradually swap parts out.
    • \n
\n

Because SuperTokens is open-source, you can try it risk-free alongside Clerk. For example, you could use Clerk for login/signup UI, but configure Supabase (or your backend) to accept SuperTokens’ tokens for session validation, leveraging SuperTokens’ defenses.

\n

Migrating from Clerk to SuperTokens

\n

If you want to move from Clerk to SuperTokens, you don’t need to rip everything out. You can migrate gradually:

\n
    \n
  • Start by having SuperTokens manage the session (tokens) while still using Clerk’s front end.
    • \n
  • Swap out Clerk’s session cookie with SuperTokens’ cookies under the hood.
    • \n
  • Replace one signup/signin flow at a time with SuperTokens recipes.
    • \n
\n

SuperTokens provides guides on migrating from other auth systems, making the process smoother.

\n

Clerk + Supabase Is a Great Start, But SuperTokens Takes You Further

\n

To summarize, the Clerk + Supabase integration we built gives you:

\n
    \n
  • A complete app with secure user sign-in.
    • \n
  • Personalized data storage (each user only sees their charts).
    • \n
  • Row-Level Security enforcing data isolation.
    • \n
\n

This is elegant and suitable for many projects. Clerk handles auth beautifully, and Supabase handles data. But if your project has higher security needs or unusual requirements, SuperTokens can take you further. With SuperTokens, you can finely tune session lifetimes, detect stolen tokens, revoke individual sessions, and even self-host everything.

\n

In Part II of this series, we’ll swap Clerk out for SuperTokens in our app and show how to achieve similar functionality (login UI, user-specific data, RLS) with maximum control over sessions.

\n

Regardless of which tools you choose, you now have a solid blueprint: Clerk (or another provider) for authentication, Supabase for data storage, and well-configured RLS to tie it all together. By adding SuperTokens into the mix, you gain an extra layer of security and flexibility.

","frontmatter":{"date":"June 03, 2025","title":"How to Integrate Clerk with Supabase (Plus another option for the curious)","cover":"integrate-clerk-with-supabase.png","author":"Maria Shimkovska","description":"🔐 Learn how to integrate Clerk with Supabase for powerful authentication and database management in your Next.js applications - with step-by-step tutorial and code examples."},"fields":{"slug":"/how-to-integrate-clerk-with-supabase/"}},"site":{"siteMetadata":{"title":"SuperTokens Blog"}}},"pageContext":{"id":"7baf501e-ac4e-5a45-8739-1076a2074ff9","fields__slug":"/how-to-integrate-clerk-with-supabase/","__params":{"fields__slug":"how-to-integrate-clerk-with-supabase"}}}, "staticQueryHashes": []}