Next.js + Supabase Standards

A curated collection of 60+ opinionated, production-proven best practices for building full-stack applications with Next.js (App Router) and Supabase.

What's Covered

Project Structure — Route groups, file naming, component organization
Data Fetching — Server components, parallel fetches, caching strategies
Supabase Auth — Client types, middleware, session management
RLS & Database — Policy patterns, migration best practices
Server Actions — Auth, validation, error handling
Component Patterns — Server vs client boundaries, Suspense, error boundaries
TypeScript — Strict mode, generated types, discriminated unions
Performance — Image optimization, dynamic imports, bundle analysis
Error Handling — Error boundaries, structured logging, user-friendly messages
Security — Input validation, SSRF prevention, CSP headers
Testing — RLS tests, server action tests, integration patterns

Why These Standards?

These standards are researched from production codebases, official documentation, and community consensus. They represent 2025-2026 best practices — not outdated patterns.

Each rule includes:

Why it matters
Good and bad code examples
Detection hints for automated enforcement
Effort level to fix

Next.js + Supabase Standards

Security(17)

Scope all mutations to the authenticated organization

Architecture(7)

Keep server actions in dedicated files

Performance(9)

Use server components for data fetching by default

Quality(20)

Handle Supabase query errors explicitly

Automate Next.js + Supabase Standards checks on every PR

Write restrictive RLS policies — deny by default

Never hardcode API keys or secrets in source code

Enable RLS on every table

Never import server-only code in client components

Store sensitive env vars without NEXT_PUBLIC_ prefix

Never expose the service_role key to the client

Use three distinct Supabase client types

Call auth.getUser() immediately after creating the server client in middleware

Use requireAuth() as the first call in every authenticated server action

Mark server modules with import "server-only"

Never use the admin client for reads in server actions

Never pass server-only data as props to client components

Validate and sanitize all user input

Test RLS policies explicitly

Use the anon key for public-facing pages

Validate all server action inputs at the boundary

Query Supabase directly in server components — skip API routes

Use route groups to organize app sections

Use a helper function for org-scoped RLS checks

Use a lib/ directory for shared utilities

Use SWR or React Query for client-side real-time data

Colocate page files with their route segment

Parallelize independent data fetches with Promise.all

Server components by default — client only when needed

Push "use client" boundary as low as possible

Use next/image for all images

Use (select auth.uid()) instead of auth.uid() in policies

Add indexes on foreign keys and common query filters

Never fetch the same data in both layout and page

Use dynamic imports for heavy client components

Use revalidatePath after server action mutations

Use error.tsx for route-level error boundaries

Enable strict mode in tsconfig.json

Never use any — use unknown for truly unknown types

Add error.tsx to every route group

Use structured logging — never console.log in production

Keep .env.example in sync with actual environment variables

Test server actions in isolation

Return the supabaseResponse object unchanged from middleware

Remember the Supabase query builder is immutable

Use unique, timestamped migration filenames

Organize components into atoms, molecules, organisms

Use loading.tsx for route-level loading states

Type your Supabase client with generated database types

Use notFound() for invalid dynamic route params

Use kebab-case for file and directory names

Return structured results from server actions

Revalidate all affected paths after mutations

Use moddatetime triggers for updated_at columns

Next.js + Supabase Standards

What's Covered

Why These Standards?