Explore

On successful creation respond with 201 Created, a Location header pointing to the new resource, and ideally its representation.

Expose filtering, sorting, and field selection through query parameters rather than proliferating bespoke endpoints.

Use plural nouns for collections and one consistent casing (e.g. snake_case or camelCase) for fields across the entire API.

Require authentication on all non-public routes and enforce per-resource authorization (object-level) on every request.

Return collections in bounded pages with a default and maximum page size, exposing next/prev cursors or links.

Return sanitized error messages for 4xx/5xx; log full stack traces server-side only and never expose them to clients.

Every error response should share one machine-readable shape (code, message, details) so clients can parse failures uniformly.

Accept a client-supplied Idempotency-Key header on create/payment endpoints so retried requests do not create duplicate resources.

GET must be safe and idempotent, PUT/DELETE idempotent, and POST for non-idempotent creates. Never mutate state on a GET.

Model endpoints as nouns representing resources, not verbs. Let HTTP methods express the action instead of encoding it in the path.

Use createClient() for authenticated pages (RLS enforced), createAdminClient() for server-side writes (service_role), and createReadOnlyClient() for public pages (anon key).

Supabase client calls are NOT automatically deduplicated like fetch(). Querying the same data in layout.tsx and page.tsx doubles database load.

Supabase's .eq(), .filter(), .order() return new builder objects. Calling them without reassignment does nothing.

Server components can query Supabase directly. Don't create API route middlemen just to proxy Supabase queries.

Fetch data in async server components instead of client-side useEffect + fetch patterns.

The SUPABASE_SERVICE_ROLE_KEY must never be in a NEXT_PUBLIC_ env var or imported in "use client" files.

Add import "server-only" to any module that uses secrets, database connections, or server-only APIs.

Per Supabase docs: do not run code between createServerClient and supabase.auth.getUser(). A simple mistake could cause random logouts.

Use database triggers to auto-update updated_at instead of setting it in application code.

Use the Image component from next/image instead of raw HTML img tags. It auto-optimizes format, size, and loading.

Maintain a .env.example file with all required variables (no values). New developers can't set up the project without it.

RLS defaults to deny all. Only add the specific policies you need. Never use USING (true) on private tables.

PostgreSQL does NOT auto-index foreign keys. Queries filtering by organization_id or repository_id will full-table-scan without explicit indexes.

Creating a new NextResponse without copying Supabase cookies breaks session management and causes random logouts.