Supabase gives a Next.js app a Postgres database, authentication, file storage, realtime updates and server functions from one project. Create a project, put the URL and the publishable key in .env.local, and write each table in a migration that grants Data API access, enables Row Level Security and adds policies. Use @supabase/ssr for the browser and server clients and a proxy.ts that refreshes the session, protect pages with getClaims(), then deploy the app to a host such as Vercel. The free plan covers 50,000 monthly active users and a 500 MB database.
This Supabase tutorial builds a small task app on Next.js: one table, sign-in, policies so each user sees only their own rows, then realtime, storage, server functions and deployment. Supabase is a hosted Postgres database with authentication, storage, realtime and edge functions around it, so a full-stack app needs one backend instead of five.
Checked on 14 October 2026 against Supabase's pricing page, its docs on API keys, Auth with Next.js, Row Level Security, Realtime, Edge Functions, Storage and migrations, and its announcement on table grants. An earlier version of this page used the legacy key names and older free plan figures; both are updated here.
- 1Create a Supabase project
Pick the region nearest your users and save the database password.
- 2Copy the URL and publishable key
Into .env.local in your Next.js app.
- 3Write the table as a migration
Table, grant, Row Level Security and policies in one file.
- 4Add the clients and proxy.ts
From @supabase/ssr: one for the browser, one for the server.
- 5Protect pages with getClaims()
Never trust getSession() in server code.
- 6Add realtime, storage or functions
Only the parts the app needs.
- 7Deploy
Push migrations with the CLI and the app to your host.
What is Supabase?
A Postgres database with the backend services an app usually needs built around it. You write ordinary SQL, and the browser talks to the database through Supabase's Data API, with Row Level Security deciding which rows each request can touch.
| Part | What it is | What you use it for |
|---|---|---|
| Database | A full Postgres database with a table editor and SQL editor | Your data, with policies that decide who sees what |
| Auth | Email and password, magic links, OAuth providers and phone sign-in | auth.uid() inside policies names the signed-in user |
| Data API | Read and write tables from the browser or server through supabase-js | Reaches only tables with a grant, and RLS filters every row |
| Realtime | Database changes, broadcast messages and presence over WebSockets | Live lists, notifications, who is online |
| Storage | Files in public or private buckets | Private buckets use policies on storage.objects |
| Edge Functions | Server-side TypeScript on the Supabase Edge Runtime, a Deno-compatible environment | Webhooks, secret API keys, low-latency endpoints |
The design choice that matters most: the browser talks to the database directly. That is fast to build with, and it means your policies are the security boundary, not your frontend code. Read Supabase RLS explained before you ship anything with real users.
Step 1: set up the project and keys
- Sign up at supabase.com, choose New project, name it, set a strong database password and pick the region closest to your users.
- Install the packages in your Next.js app:
npm install @supabase/supabase-js @supabase/ssr. - Copy the project URL and the publishable key into
.env.local:
NEXT_PUBLIC_SUPABASE_URL=https://<project-ref>.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...- Secret key: sb_secret_...
- Legacy service_role key
- Both bypass Row Level Security
- Server code and Edge Functions only
- Publishable key: sb_publishable_...
- Legacy anon key
- Row Level Security limits what they reach
- Fine in client code and public repositories
Source: Supabase API keys docs, read 14 October 2026
Supabase is deprecating the anon and service_role keys by the end of 2026. Creating the new keys does not revoke the old ones; both work side by side until you disable the legacy keys under Settings, API Keys. Older tutorials, including the first version of this one, use NEXT_PUBLIC_SUPABASE_ANON_KEY; the current Next.js guide names the variable NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY.
Step 2: create a table with grants and Row Level Security
Write every table as SQL in a migration, and give each one three things in the same file: a grant, Row Level Security and policies. The task table:
create table public.tasks (
id uuid primary key default gen_random_uuid(),
user_id uuid not null default auth.uid() references auth.users (id) on delete cascade,
title text not null,
done boolean not null default false,
created_at timestamptz not null default now()
);
-- 1. Let signed-in users reach the table through the Data API
grant select, insert, update, delete on public.tasks to authenticated;
-- 2. Turn on Row Level Security
alter table public.tasks enable row level security;
-- 3. Each user sees and changes only their own rows
create policy "Read own tasks" on public.tasks
for select to authenticated using ((select auth.uid()) = user_id);
create policy "Add own tasks" on public.tasks
for insert to authenticated with check ((select auth.uid()) = user_id);
create policy "Update own tasks" on public.tasks
for update to authenticated using ((select auth.uid()) = user_id);
create policy "Delete own tasks" on public.tasks
for delete to authenticated using ((select auth.uid()) = user_id);Why the three parts. The grant decides whether a role can reach the table at all. Row Level Security, once enabled, blocks every row until a policy allows it: Supabase's docs say no data is accessible through the API with a publishable key until you create policies. The policies then say which rows. Wrapping auth.uid() in (select ...) is the form Supabase's own examples use. For teams and organisations, our multi-tenant RLS guide extends the same pattern.
Step 3: add authentication to Next.js
Use @supabase/ssr, which stores the session in cookies so both server and browser code can read it. Supabase's Next.js guide sets up three pieces:
- 01Browser client
createBrowserClient, for sign-in forms and client components.
- 02proxy.ts
Refreshes the session on each request with getClaims() and writes fresh cookies.
- 03Server client
createServerClient, made per request from that request's cookies.
- 04getClaims() check
Verifies the token before a page or action touches user data.
- 05Query
RLS returns only the rows this user may see.
The server client, as the guide writes it:
// 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_PUBLISHABLE_KEY!,
{
cookies: {
getAll() { return cookieStore.getAll() },
setAll(cookiesToSet) {
try {
cookiesToSet.forEach(({ name, value, options }) => cookieStore.set(name, value, options))
} catch {
// Called from a Server Component: proxy.ts refreshes the session instead.
}
},
},
},
)
}And a protected page that lists the user's tasks:
// app/tasks/page.tsx
import { createClient } from '@/lib/supabase/server'
export default async function TasksPage() {
const supabase = await createClient()
const { data: claims } = await supabase.auth.getClaims()
if (!claims) return <p>Sign in to see your tasks.</p>
// RLS returns only this user's rows; no where clause needed.
const { data: tasks } = await supabase
.from('tasks')
.select('id, title, done')
.order('created_at')
return <ul>{tasks?.map(t => <li key={t.id}>{t.title}</li>)}</ul>
}- The proxy file name depends on your Next.js version. On Next.js 16 it is
proxy.ts; on 15 and earlier it ismiddleware.ts. Supabase warns that aproxy.tson an older version is never called, so sessions never refresh and users get signed out. Copy the file from the guide. - Never trust
getSession()in server code. It reads the cookie without checking it, and anyone can forge that cookie. UsegetClaims()to protect pages and data, andgetUser()when you need a fresh record from the Auth server.
Step 4: add realtime updates
Add the table to the supabase_realtime publication, then subscribe from a client component:
alter publication supabase_realtime add table public.tasks;supabase
.channel('tasks')
.on('postgres_changes', { event: '*', schema: 'public', table: 'tasks' }, payload => {
// update the list from payload.new / payload.old
})
.subscribe()Postgres Changes checks each event against each subscriber's policies, so users only receive their own rows, with one exception in Supabase's Realtime docs: RLS is not applied to delete events. Because the check runs once per subscriber, the docs suggest Broadcast instead beyond about 3,000 concurrent subscribers on the same changes. Presence, for who is online, is a separate Realtime feature.
Step 5: store files
Files live in buckets, and the bucket type decides how reads work. In a private bucket, every operation, downloads included, goes through policies on the storage.objects table, and you share a file with a signed URL that expires. In a public bucket, anyone with the URL can read a file; uploads, deletes and moves still need a policy. Use private for anything a user uploads, public for assets like product images (storage docs). Size limits and allowed file types are set per bucket.
Step 6: when do you need Edge Functions?
When code must run on a server and you do not already have one. Supabase Edge Functions are TypeScript functions on the Supabase Edge Runtime, a Deno-compatible environment, served from the region nearest the caller (Edge Functions docs). Typical jobs: receiving a webhook, calling an API with a secret key, or an endpoint that has to be fast everywhere.
In a Next.js app you often do not need them: a Server Action or Route Handler can hold a secret just as well. Keep secrets in Supabase project secrets, read them as environment variables, and run functions locally with supabase functions serve. If a function handles payments, our guide to testing Stripe webhooks locally covers the testing loop.
Step 7: deploy
Deploy the database changes and the app separately. The schema goes up as migrations with the Supabase CLI:
supabase migration new create_tasks_table # write the SQL above into the new file
supabase migration up # apply it to your local database
supabase link # connect the CLI to your hosted project
supabase db push # apply pending migrations to itThe Next.js app goes to any host that runs it, such as Vercel. Add NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY to the host's environment variables, and keep any secret key in server-only variables without the NEXT_PUBLIC_ prefix. Then add your production URL to the allowed redirect URLs in Supabase Auth so sign-in links return to the right place.
- Every table in public has Row Level Security enabled and tested policies
- New tables carry their grants in the migration that creates them
- The browser only ever sees the publishable key
- Server code checks getClaims(), never getSession()
- proxy.ts or middleware.ts matches your Next.js version
- Private buckets for anything users upload
- Delete events in Realtime are not relied on for access control
- The plan fits: free projects pause after a week of inactivity
What does Supabase cost?
Nothing to start, and $25 a month once the app matters. The two plans most solo builders choose between, per the pricing page on 14 October 2026:
| Free | Pro | |
|---|---|---|
| Price | From $0 a month | From $25 a month |
| Monthly active users | 50,000 | 100,000, then $0.00325 each |
| Database | 500 MB | 8 GB disk per project, then $0.125 per GB |
| Egress | 5 GB | 250 GB, then $0.09 per GB |
| File storage | 1 GB | 100 GB, then $0.0213 per GB |
| Edge Function invocations | 500,000 | 2 million, then $2 per million |
| Realtime connections | 200 concurrent | 500 concurrent |
| Inactivity | Paused after 1 week; 2 active projects | Not paused; spend cap on by default |
The free plan's pause is the practical limit: a side project that nobody uses for a week stops answering until you restore it. Pro includes $10 a month of compute credits, and Team starts at $599 a month. For the wider choice of Postgres host, see our Postgres hosting comparison.
Where to go next
Add search over your own documents with pgvector on Supabase, compare starting points in Next.js SaaS boilerplates, or see the whole product path in how to build an AI SaaS. If you want the full build, from validating the idea to Stripe billing, AI SaaS Builder is our program built on this stack, with lessons on Supabase database design, authentication, the Claude API and deploying to Vercel.
Supabase tutorial: FAQ
Is Supabase free?
Supabase has a free plan. Its pricing page, read on 14 October 2026, lists 50,000 monthly active users, a 500 MB database, 1 GB of file storage, 5 GB of egress and 500,000 Edge Function invocations, with a limit of two active projects. Free projects pause after a week of inactivity. Pro starts at $25 a month and is not paused.
Which Supabase key goes in the browser?
The publishable key, which starts with sb_publishable_. Supabase's docs call it safe to expose, because Row Level Security limits what it can reach. The secret key, sb_secret_, bypasses Row Level Security and belongs only in server code. The older anon and service_role keys work the same way and are being deprecated by the end of 2026.
Why can my app not see a new Supabase table?
From 30 October 2026, Supabase stops granting Data API access to new tables in the public schema automatically, on existing projects as well as new ones. Until a grant exists, supabase-js cannot see the table. Add grant statements for the roles that need it in the same migration that creates the table, and enable Row Level Security with policies.
How do I add Supabase Auth to Next.js?
Install @supabase/supabase-js and @supabase/ssr, set NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY, and create a browser client and a server client. On Next.js 16, add a proxy.ts that refreshes the session with getClaims(). In server code, protect pages with getClaims(), never getSession(), which reads a cookie anyone can forge.
How do I handle database migrations in Supabase?
With the Supabase CLI. Create a file with supabase migration new, write the SQL, and apply it locally with supabase migration up. supabase db diff turns changes you made in a local dashboard into a migration. Then link the project with supabase link and apply the migrations to it with supabase db push.
Does Supabase Realtime respect Row Level Security?
Mostly. Postgres Changes checks each event against each subscriber, so clients only receive rows their policies allow. Supabase's docs note one exception: RLS policies are not applied to DELETE events. Because the check runs per subscriber, the docs suggest Broadcast instead once you expect more than about 3,000 concurrent subscribers on the same changes.