Introduction

The combination of Next.js 15 and Supabase has rapidly become one of the most productive stacks for building full-stack web applications. You get React Server Components, streaming SSR, and the App Router on the frontend paired with a fully managed PostgreSQL database, built-in auth, real-time subscriptions, and file storage on the backend.

In this guide we'll build a complete application from scratch, covering every layer of the stack. By the end, you'll have a production-ready app deployed to Vercel.

Prerequisites

Node.js 18+
A Supabase account (free tier works)
A Vercel account for deployment
Familiarity with React and TypeScript basics

1. Project Setup

Start by scaffolding a new Next.js project with the App Router and TypeScript:

npx create-next-app@latest my-app \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir=false
cd my-app

Then install the Supabase client libraries:

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

2. Supabase Project Configuration

Create a new project in the Supabase Dashboard. Once created, grab your Project URL and anon key from Settings → API and add them to .env.local:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

3. Database Schema Design

Good schema design is the foundation of any robust app. Here's a simple schema for a task management app run this SQL in the Supabase SQL Editor:

-- Profiles table (extends auth.users)
create table profiles (
  id uuid references auth.users on delete cascade primary key,
  username text unique not null,
  full_name text,
  avatar_url text,
  updated_at timestamptz default now()
);

-- Tasks table
create table tasks (
  id uuid default gen_random_uuid() primary key,
  user_id uuid references profiles(id) on delete cascade not null,
  title text not null,
  description text,
  completed boolean default false,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Indexes
create index tasks_user_id_idx on tasks(user_id);
create index tasks_created_at_idx on tasks(created_at desc);

4. Row-Level Security (RLS)

RLS is one of Supabase's killer features. It lets you enforce authorization rules directly in the database, so even if someone bypasses your API, they can't access data they shouldn't see.

-- Enable RLS
alter table profiles enable row level security;
alter table tasks enable row level security;

-- Profiles: users can only read/update their own profile
create policy "Users can view own profile"
  on profiles for select using (auth.uid() = id);

create policy "Users can update own profile"
  on profiles for update using (auth.uid() = id);

-- Tasks: users can only CRUD their own tasks
create policy "Users can view own tasks"
  on tasks for select using (auth.uid() = user_id);

create policy "Users can insert own tasks"
  on tasks for insert with check (auth.uid() = user_id);

create policy "Users can update own tasks"
  on tasks for update using (auth.uid() = user_id);

create policy "Users can delete own tasks"
  on tasks for delete using (auth.uid() = user_id);

5. Supabase Client Setup

With @supabase/ssr, you get separate client helpers for Server Components, Client Components, and Route Handlers:

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

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

6. Authentication with Server Components

Next.js Server Components let you check auth state server-side before rendering no flash of unauthenticated content.

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

export default async function DashboardPage() {
  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()

  if (!user) redirect('/login')

  const { data: tasks } = await supabase
    .from('tasks')
    .select('*')
    .order('created_at', { ascending: false })

  return (
    <main>
      <h1>Welcome back, {user.email}</h1>
      <TaskList tasks={tasks ?? []} />
    </main>
  )
}

7. Real-Time Subscriptions

Supabase lets you subscribe to database changes in real time using Postgres replication. Here's a client component that listens for new tasks:

'use client'
import { useEffect, useState } from 'react'
import { createClient } from '@/lib/supabase/client'
import type { Task } from '@/lib/types'

export function RealtimeTaskList({ initialTasks }: { initialTasks: Task[] }) {
  const [tasks, setTasks] = useState(initialTasks)
  const supabase = createClient()

  useEffect(() => {
    const channel = supabase
      .channel('tasks-channel')
      .on('postgres_changes', {
        event: '*',
        schema: 'public',
        table: 'tasks',
      }, (payload) => {
        if (payload.eventType === 'INSERT') {
          setTasks(prev => [payload.new as Task, ...prev])
        } else if (payload.eventType === 'DELETE') {
          setTasks(prev => prev.filter(t => t.id !== payload.old.id))
        } else if (payload.eventType === 'UPDATE') {
          setTasks(prev => prev.map(t =>
            t.id === payload.new.id ? payload.new as Task : t
          ))
        }
      })
      .subscribe()

    return () => { supabase.removeChannel(channel) }
  }, [])

  return <ul>{tasks.map(t => <li key={t.id}>{t.title}</li>)}</ul>
}

8. File Storage

Supabase Storage makes handling file uploads simple. Here's how to upload an avatar:

async function uploadAvatar(file: File, userId: string) {
  const supabase = createClient()
  const ext = file.name.split('.').pop()
  const path = `${userId}/avatar.${ext}`

  const { error } = await supabase.storage
    .from('avatars')
    .upload(path, file, { upsert: true })

  if (error) throw error

  const { data } = supabase.storage.from('avatars').getPublicUrl(path)
  return data.publicUrl
}

9. Deployment to Vercel

Deploying a Next.js + Supabase app to Vercel takes under 5 minutes:

Push your code to GitHub.
Import the repo in the Vercel dashboard.
Add your environment variables (NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY).
Click Deploy.

Vercel automatically detects Next.js and configures the build correctly. Your app will be live in ~2 minutes.

Performance Comparison

Feature	Next.js + Supabase	Traditional REST API	Firebase
Cold start	~50ms	~200ms	~80ms
Auth setup time	15 min	2–4 hrs	30 min
Real-time	✅ Built-in	❌ Custom	✅ Built-in
SQL support	✅ Full PostgreSQL	✅ Depends	❌ NoSQL only
Free tier DB size	500 MB	N/A	1 GB

Conclusion

Next.js 15 and Supabase together form one of the most powerful and developer-friendly stacks available today. You get the performance of React Server Components, the simplicity of a managed Postgres backend, and the flexibility to scale from side project to production app without changing your architecture.

The patterns covered in this guide RLS, server-side auth, real-time subscriptions, and file storage are the foundation of almost every full-stack app. Start with this as your base and build from there.

Happy shipping! 🚀

Thoughts on Code, Design & Technology

Thoughts on Code, Design & Technology

Featured Article

Building Full-Stack Apps with Next.js 15 and Supabase

Latest Articles