Explore

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

Store sensitive env vars without NEXT_PUBLIC_ prefix

Only the Supabase URL and anon key should have NEXT_PUBLIC_ prefix. All other Supabase credentials are server-only.

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).

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 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 the anon key for public-facing pages

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

Use revalidatePath after server action mutations

Call revalidatePath() or revalidateTag() after insert/update/delete operations to refresh cached pages.

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.

Never expose the service_role key to the client

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

Parallelize independent data fetches with Promise.all

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

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.

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.

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.

Handle Supabase query errors explicitly

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

Use server components for data fetching by default

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

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.

Mark server modules with import "server-only"

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

Keep server actions in dedicated files

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

Use a lib/ directory for shared utilities

LOW

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

Organize components into atoms, molecules, organisms

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

Never import server-only code in client components

Files with "use client" must never import server-only modules like database clients, API keys, or service role credentials.

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.

Colocate page files with their route segment

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

Type your Supabase client with generated database types

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