name: supabase
description: >
Supabase patterns for Next.js: SSR auth, RLS, and data access.
Trigger: Use when working with Supabase (auth, database, RLS policies).
license: Apache-2.0
metadata:
author: gpolanco
version: "1.0.0"
scope: [root]
auto_invoke: "Working with Supabase"
allowed-tools: Read

Supabase with Next.js

🚨 CRITICAL: Reference Files are MANDATORY

This SKILL.md provides OVERVIEW only. For EXACT patterns:

⚠️ DO NOT implement Supabase Auth or RLS policies without reading the corresponding reference file FIRST.

When to Use

• Setting up Supabase auth
• Querying data from Server Components
• Creating RLS policies

Cross-references:

• For Next.js patterns → See nextjs skill
• For React patterns → See react-19 skill

ALWAYS

• Use Server Client for ALL data operations
• Use Browser Client ONLY for auth UI (login/logout)
• Use getClaims() to validate tokens (not getSession())
• Enable RLS on ALL tables
• Use NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY (not legacy ANON_KEY)
• Validate via RLS policies, not application code

NEVER

• Never query data from Client Components
• Never use getSession() in server code
• Never expose service_role key in client
• Never use @supabase/auth-helpers-nextjs (deprecated)

DEFAULTS

• Data access: Server Components + Server Actions
• Auth UI: Client Components
• Session refresh: proxy.ts / middleware.ts
• prefer server client over browser client for data operations

🚫 Critical Anti-Patterns

• DO NOT query data from Client Components → always use Server Components or Server Actions.
• DO NOT use @supabase/auth-helpers-nextjs (deprecated) → use @supabase/ssr.
• DO NOT use getSession() in server code → use getUser() to avoid security vulnerabilities.
• DO NOT expose service_role key in client → it bypasses all RLS policies.

Quick Reference

Install

pnpm add @supabase/supabase-js @supabase/ssr

Environment

NEXT_PUBLIC_SUPABASE_URL=<url>
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=<key>

Data Pattern

// ✅ Server Component - use server client
import { createClient } from "@/lib/supabase/server";

export const UserList: React.FC = async () => {
  const supabase = await createClient();
  const { data } = await supabase.from("users").select();
  return <ul>{data?.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
};

// ❌ Client Component - NEVER query data
"use client";
const supabase = createClient();
supabase.from("users").select(); // WRONG!

Auth Check

// Protected layout
const supabase = await createClient();
const {
  data: { user },
} = await supabase.auth.getUser();
if (!user) redirect("/login");

RLS Quick Pattern

-- Users read own data
CREATE POLICY "read_own" ON profiles
FOR SELECT TO authenticated
USING (auth.uid() = user_id);

Resources

• Full Auth Setup: reference/auth-nextjs.md - Complete workflow
• RLS Patterns: reference/rls-patterns.md - Policy examples
• Official Docs: Supabase + Next.js