Explore

Use supabase gen types typescript to generate types from your schema, then pass them as a generic: createClient<Database>().

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

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

Use three distinct Supabase client types

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

Parallelize independent data fetches with Promise.all

Use Promise.all for independent Supabase queries instead of sequential await chains.

Never fetch the same data in both layout and page

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

Use the anon key for public-facing pages

Public pages (explore, content detail) should use createReadOnlyClient() with the anon key, not the service_role.

Use server components for data fetching by default

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

Mark server modules with import "server-only"

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

Use route groups to organize app sections

Organize routes using parenthesized layout groups like (auth), (dashboard), (content), (marketing) for separate layouts and clear separation of concerns.

Enable RLS on every table

Every table must have Row Level Security enabled. Tables without RLS are fully accessible via the anon key.

Use a lib/ directory for shared utilities

LOW

Centralize shared logic (auth, database clients, formatters) in a lib/ directory to avoid duplication.

Handle Supabase query errors explicitly

Always check the error field from Supabase queries. The client returns { data, error } and never throws.

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

Wrapping auth.uid() in (select ...) ensures it's evaluated once per query instead of once per row.

Colocate page files with their route segment

Keep page.tsx, layout.tsx, loading.tsx, and error.tsx together in the same route segment directory.

Keep server actions in dedicated files

Place server actions in separate *-actions.ts files rather than inline in page components.

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

For data that changes frequently (notifications, dashboards), use SWR or React Query instead of manual useEffect + fetch.

Use kebab-case for file and directory names

Name files and directories in kebab-case (lowercase with hyphens) to avoid cross-platform case sensitivity issues.

Use moddatetime triggers for updated_at columns

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

Use loading.tsx for route-level loading states

Add loading.tsx to route segments with slow data fetching. It provides instant visual feedback during navigation.

Use error.tsx for route-level error boundaries

Every route group should have an error.tsx to prevent crashes from propagating to the entire app.

Query Supabase directly in server components — skip API routes

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

Use notFound() for invalid dynamic route params

When a dynamic route param doesn't match any record, call notFound() from next/navigation to show the 404 page.

Organize components into atoms, molecules, organisms

Use atomic design to structure components: atoms (Button, Input), molecules (SearchBar, FormField), organisms (Header, Sidebar).

Never hardcode API keys or secrets in source code

Always use environment variables for API keys, database credentials, and other secrets.