Getting Started with Supabase

Supabase is essentially:

• a hosted Postgres database
• authentication
• storage
• realtime

…and a set of tools around it.

This guide focuses on the parts that matter most when you’re building a production Next.js app.

---

1) Project setup: environment variables

Keep your environment variables organized:

• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY
• SUPABASE_SERVICE_ROLE_KEY (server-only)

Never expose the service role key to the client.

Rules of thumb:

• Only variables prefixed with NEXT_PUBLIC_ are accessible in the browser
• Anything that can bypass RLS must stay server-only
• Treat env files as secrets, not config dumps

---

2) Use Postgres as the source of truth

Even if you start simple, you’ll appreciate Postgres later:

• constraints
• indexes
• migrations
• joins

If you’re using Prisma, treat Supabase as “just Postgres”.

Supabase adds convenience, but your data model should remain portable and well-structured.

---

3) Row Level Security (RLS) is not optional

RLS is the #1 reason Supabase apps stay secure.

Basic idea:

• tables are locked down by default
• you add policies for what users can read/write

Example policy:

sql
-- Only allow users to read their own rows
CREATE POLICY "Users can read own profile"
ON profiles
FOR SELECT
USING (auth.uid() = user_id);

If you disable RLS “just to make it work”, you’re creating a future security incident.

---

4) Auth: keep server and client responsibilities separate

Client-side:

• sign-in UI
• session-aware components
• optimistic UX

Server-side:

• protected API routes
• privileged writes
• service-role access when required

If you’re also using NextAuth, be careful not to create two competing auth systems. Pick one as the primary source of identity.

---

5) Storage: validate file types and paths

When uploading to Supabase Storage:

• validate mime type
• validate max size
• write predictable paths like blogs/<slug>/<filename>
• set correct cache headers

Use Storage for binary assets (images, files), not for Markdown or structured content.

---

6) Performance tips

• Create indexes early for frequent filters
• Prefer pagination with LIMIT / OFFSET or cursor patterns
• Avoid select * in hot paths
• Keep payloads small for client-side queries

Remember: Postgres performance issues are usually schema or query issues, not Supabase issues.

---

7) Deployment gotchas

• Use the transaction pooler for runtime connections when needed
• Use a direct DB connection for migrations
• Don’t run migrations in serverless cold starts
• Avoid rebuilding your app just to update content; content should live in the DB

---

README checklist (recommended)

Add this checklist to your README to avoid common production mistakes:

Security & RLS

• RLS enabled on all public tables
• No USING (true) policies in production
• Service role key never exposed to client
• Auth-based policies use auth.uid() correctly

Environment variables

• NEXT_PUBLIC_* vars reviewed and intentional
• Service role key used only on server
• .env.local excluded from version control

Data & content

• Blogs and projects stored in Postgres, not hardcoded files
• Markdown stored as raw text (no CSV imports for content)
• Admin edits write directly to DB

Performance & correctness

• Indexes added for common filters
• Pagination implemented for large lists
• Cache invalidation or revalidation handled on updates

---

Closing

Supabase is a great “batteries included” platform, but the real power is:

you’re still using Postgres

If your app is secure, fast, and maintainable, it’s because your data model and policies are solid; not because of magic abstractions.