How to Use Supabase with Next.js (Complete Guide)

Supabase with Next.js is a powerful combination if you set it up correctly — and a confusing mess if you mix up the browser and server clients. The key insight: the App Router needs two separate clients for sessions to work server-side. Here's the complete guide, including when to reach for Prisma on the same Postgres.

Quick Answer

To use Supabase with Next.js, install the Supabase client, create separate browser and server clients, and use the server client inside Server Components and route handlers so sessions are read from cookies. Supabase gives you a hosted PostgreSQL database, authentication, and storage behind one SDK. Because it is plain PostgreSQL underneath, you can also point an ORM like Prisma at the same database when you outgrow the SDK.

What Supabase is

Supabase is a hosted backend platform built on PostgreSQL that provides a database, authentication, and storage through a single SDK. It is often described as an open-source Firebase alternative — see the full comparison in Supabase vs Firebase.

Prerequisites

• A Next.js App Router app (Node 20+).

• A Supabase project (free tier is fine) with its URL and anon key.

• @supabase/supabase-js and @supabase/ssr installed.

npm install @supabase/supabase-js @supabase/ssr

Step 1: Create browser and server clients

Next.js runs code in two places, so you need two clients. The browser client uses the public anon key; the server client reads and writes the auth cookie. (Untested-here: illustrative, follow the current Supabase SSR docs for exact helper signatures.)

// lib/supabase/server.ts
import { createServerClient } from '@supabase/ssr';
import { cookies } from 'next/headers';

export async function supabaseServer() {
  const cookieStore = await cookies();
  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll: () => cookieStore.getAll(),
        setAll: (toSet) =>
          toSet.forEach(({ name, value, options }) =>
            cookieStore.set(name, value, options)
          ),
      },
    }
  );
}

Step 2: Read the session on the server

Use the server client in a Server Component so authentication is enforced before the page renders. The full server-side pattern is in Supabase SSR with Next.js.

// app/dashboard/page.tsx
import { redirect } from 'next/navigation';
import { supabaseServer } from '@/lib/supabase/server';

export default async function Dashboard() {
  const supabase = await supabaseServer();
  const { data: { user } } = await supabase.auth.getUser();
  if (!user) redirect('/login');
  return <h1>Hello {user.email}</h1>;
}

Step 3: Query data

Once you have a client, querying is one call. Supabase returns typed rows from your PostgreSQL tables.

const { data: posts, error } = await supabase
  .from('posts')
  .select('id, title')
  .order('created_at', { ascending: false });

Supabase vs Prisma/PostgreSQL (an honest note)

Supabase's SDK is great for getting started and for its built-in auth and realtime. But Supabase is PostgreSQL, so as your data layer grows you can also use a typed ORM like Prisma against the same database for migrations and complex queries — see Prisma tutorial. Many production teams use the Supabase SDK for auth and a typed query layer for the rest.

Common issues

Session is null in a Server Component

You are probably using the browser client on the server, or not wiring the cookie handlers. Use the server client (Step 1) so the auth cookie is read.

Row Level Security blocks your query

Supabase enables RLS by default. Add policies for the tables you query, or you will get empty results with no obvious error.

How FastStaq fits

FastStaq uses PostgreSQL via Prisma as its data layer, so it runs on any Postgres host — including Supabase's managed PostgreSQL — by pointing DATABASE_URL at it. FastStaq does not bundle the Supabase SDK; it owns its auth and data layer on plain Postgres, which is the same relational engine Supabase runs. If you like Supabase's hosted Postgres, you can use it as FastStaq's database.

Frequently asked questions

How do I use Supabase with the Next.js App Router? Create separate browser and server clients with @supabase/ssr and use the server client in Server Components and route handlers.

Is Supabase the same as PostgreSQL? Supabase is built on PostgreSQL and adds auth, storage, realtime, and an SDK on top.

Can I use Prisma with Supabase? Yes — point Prisma's DATABASE_URL at your Supabase Postgres connection string.

Next steps

• Supabase SSR with Next.js

• Supabase tutorial for beginners

• How to build API routes in Next.js

• Supabase vs Firebase

• Back to the SaaS boilerplate guide