"53 opinionated, production-proven rules and 12 in-depth guides for building full-stack Next.js + Supabase applications. Human-researched, not AI-generated."
Ask an AI assistant how to structure a Next.js + Supabase app and you'll get a different answer every time. Google it and you'll find contradictory advice across dozens of blog posts. Ask your team and you'll discover everyone has a slightly different approach.
There's no single, curated, stack-specific source of truth for "how should a modern Next.js + Supabase project be built?"
Until now.
Today we're releasing the Next.js + Supabase Standards Library — 53 opinionated rules and 12 in-depth guides covering every layer of a full-stack Next.js + Supabase application.
Every rule is:
| Category | Rules | Examples |
|---|---|---|
| Security | 17 | Enable RLS on every table, never expose service_role key, validate server action inputs |
| Architecture | 7 | Use route groups, keep server actions in dedicated files, use RLS helper functions |
| Quality | 20 | Handle Supabase errors explicitly, use error.tsx boundaries, structured logging |
| Performance | 9 | Server components by default, parallelize independent fetches, dynamic imports |
Deep-dive articles that explain the why behind the rules:
createClient() vs createAdminClient() vs createReadOnlyClient(), and why getting it wrong is a security vulnerabilityPlus guides on data fetching, database migrations, auth flows, TypeScript patterns, testing, and performance optimization.
AI assistants are great for writing code. They're terrible at consistency. Ask Claude or ChatGPT the same architecture question twice and you'll get different answers. They don't know your team decided to use requireAuth() as the first call in every server action, or that your RLS policies all go through is_org_member().
These standards are the missing layer — the opinionated decisions your team makes once so AI and humans enforce them consistently.
When you install BeforeMerge standards, they're injected into every AI-generated suggestion. Instead of generic advice, you get recommendations that reference your standards.
Every PR gets scanned against all 53 rules. Violations show up as findings with AI-generated fix suggestions that reference your installed standards.
The rules and guides are open source across two repos:
Browse, fork, adapt to your team. Contributions welcome via PR (CLA required for first-time contributors).
This is the #1 Supabase bug we see. The query builder returns a new object — calling .eq() without reassigning silently does nothing:
// BAD: filter silently ignored
let query = supabase.from("scans").select("*")
query.eq("status", "active") // return value discarded!
const { data } = await query // returns ALL scans
// GOOD: reassign the result
let query = supabase.from("scans").select("*")
query = query.eq("status", "active")
const { data } = await query // returns only active scanscreateAdminClient() bypasses all RLS policies. Using it for SELECT queries removes your safety net — a missing WHERE clause returns data from every organization:
// BAD: bypasses RLS, sees all orgs
const admin = createAdminClient()
const { data } = await admin.from("scans").select("*")
// GOOD: RLS enforced, only sees user's org
const supabase = await createClient()
const { data } = await supabase.from("scans").select("*")This one comes straight from the Supabase docs: "Do not run code between createServerClient and supabase.auth.getUser()." Violating this causes users to be randomly logged out with no clear cause. We've seen it happen.
This is the first standards collection — focused on our own stack (Next.js + Supabase). Coming next:
We're also working on Convention Detection — BeforeMerge will analyze your codebase, detect your existing patterns, and propose them as enforceable rules. Your conventions, automatically documented and enforced.
Standards shouldn't live in someone's head. They should be written down, enforced automatically, and improved over time. That's what BeforeMerge does.