How to Add Supabase to Next.js (2026 Step-by-Step Guide)

Supabase is a hosted Postgres with a REST + realtime layer on top, plus prebuilt auth and file storage. You write SQL (or use their query builder) for everything; auth is JWT-based and integrates with Postgres Row Level Security (RLS) so authorization is enforced at the database, not in your application code. The whole package competes with Firebase, but on top of real SQL.

When to pick Supabase: you want Postgres, you want auth without rolling your own, and you want it to scale to real traffic without managing infrastructure. When NOT to pick: you specifically need a particular ORM (Drizzle, Prisma) — they work but aren't the canonical path; or you want zero vendor lock-in (the auth tables are Supabase-specific).

supabase.com → New project → pick a region close to your users. Two URLs and two keys: `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY` (safe to expose; respects RLS), and `SUPABASE_SERVICE_ROLE_KEY` (NEVER expose — bypasses RLS, used only in server code).

`npm i @supabase/supabase-js @supabase/ssr`. The `@supabase/ssr` package handles the Next.js App Router cookie pattern — it's what reads the auth session in Server Components.

Create `lib/supabase/client.ts` (browser client using anon key), `lib/supabase/server.ts` (server client using cookies from headers, also anon key but with the session attached), and `lib/supabase/admin.ts` (service-role client for admin operations — never imported in Client Components).

Open the SQL editor in Supabase. Create your tables. The killer feature is Row Level Security — policies that filter which rows a user can read/write based on their `auth.uid()`. With RLS on, you literally can't accidentally leak another user's data, because the database itself enforces the check.

Example: `CREATE TABLE projects (id uuid PRIMARY KEY DEFAULT gen_random_uuid(), user_id uuid REFERENCES auth.users, name text NOT NULL); ALTER TABLE projects ENABLE ROW LEVEL SECURITY; CREATE POLICY "users see own projects" ON projects FOR SELECT USING (auth.uid() = user_id);` — now every query against `projects` is automatically filtered to rows the calling user owns.

Generate TypeScript types: `npx supabase gen types typescript --project-id=YOUR_REF > lib/database.types.ts`. Pass this to `createClient<Database>()` and you get full type-safety on every query.

Supabase auth supports email/password, magic links, OAuth (Google, GitHub, Apple, etc.), and one-time passwords. Configure providers in the dashboard → Authentication → Providers.

On the client: `await supabase.auth.signInWithPassword({ email, password })` returns a session. The session is stored in cookies (using `@supabase/ssr`) so it survives across pages and works server-side.

Protect pages in a Server Component: `const { data: { user } } = await supabase.auth.getUser(); if (!user) redirect('/login')`. The auth check happens at the database boundary thanks to RLS — even if you forget the user check, the data won't leak.

In a Server Component (the default in App Router): `const supabase = createServerClient(...)`. Then `const { data: projects } = await supabase.from('projects').select('*').order('created_at', { ascending: false })`. The query runs server-side, types come from your generated types file, RLS filters automatically.

For mutations, use Server Actions: a function marked `'use server'` that calls `supabase.from('projects').insert({ name }).select().single()`. Server Actions are tied to form submissions and revalidate cached data automatically.

Avoid mixing client-side and server-side fetching for the same data — pick one path per page. Server Components fetch on the server (faster initial paint, no client bundle). Client Components fetch with `useQuery` (interactive features, optimistic updates).

Create a bucket in the dashboard → Storage. Set its RLS policies (e.g., 'users can read their own files'). Upload from the client: `await supabase.storage.from('avatars').upload(\`\${userId}/avatar.png\`, file)`. Files get a public URL or a signed temporary URL depending on the bucket's policy.

Avoid storing huge files (>50MB) — Supabase storage isn't optimized for it, and S3 directly is cheaper at scale. Use it for user avatars, document attachments, small media — the long tail of small files apps need.

`const channel = supabase.channel('public:projects').on('postgres_changes', { event: '*', schema: 'public', table: 'projects' }, (payload) => { /* update local state */ }).subscribe()` — your client gets a websocket message every time the `projects` table changes.

Use this for collaborative features: presence (who's online), live counters, multiplayer editors. Don't use it as a substitute for proper data fetching — it's an event stream, not a query API.

Connection pooling: Supabase has two ports — 5432 (direct) and 6543 (pooler). Use 6543 in serverless environments (Vercel, AWS Lambda) — direct connections will exhaust the database limit fast under traffic.

Backups: Supabase backs up daily for free, hourly with Pro. For mission-critical data, add an external backup pipeline (pg_dump to S3 nightly via a cron job).

Costs: free tier is 500MB database + 1GB storage + 50k MAU. Pro is $25/mo. Once you exceed those, costs scale linearly. Monitor in the dashboard → Reports.