feat: supabase sdk references

[Rodriguespn]

What kind of change does this PR introduce?

Adds comprehensive Supabase JS SDK reference documentation.

What is the current behavior?

The Supabase skill previously focused on database-level patterns (RLS policies, schema design, migrations, performance optimization). While it covered essential backend patterns, it lacked guidance for frontend developers working with the supabase-js SDK, including:

• No client initialization patterns for browser vs server contexts
• No TypeScript type generation workflows
• No query patterns with filters, joins, and RPC calls
• No error handling guidance for the { data, error } API pattern
• No framework-specific integration guides (Next.js App Router)
• No realtime subscription cleanup patterns

This gap meant developers had to frequently consult external documentation for SDK-specific patterns.

What is the new behavior?

Added 14 new reference files under skills/supabase/references/sdk/ organized into 6 logical sections:

Client Initialization (CRITICAL):

• Browser client setup with singleton pattern via createBrowserClient
• Server client with cookie handling for SSR using createServerClient
• Configuration options including React Native setup

TypeScript (HIGH):

• Generating types from database schema using Supabase CLI
• Using the Database generic with Tables/Enums helpers
• QueryData helper for complex join types

Query Patterns (HIGH):

• CRUD operations with proper type safety
• Filters and modifiers (eq, gt, ilike, order, limit)
• Relations and joins with foreign tables
• RPC calls to Postgres functions

Error Handling (MEDIUM-HIGH):

• Checking errors before using data
• Error types for Edge Functions
• Retry patterns with custom fetch

Performance (HIGH):

• Query optimization (select specific columns, parallel queries)
• Realtime subscription cleanup to prevent memory leaks
• Scale considerations (Broadcast vs Postgres Changes)

Framework Integration (HIGH):

• Complete Next.js App Router setup with middleware
• Server Components vs Client Components
• Server Actions with revalidation
• Common SSR pitfalls and solutions

Decisions

Key architectural and content decisions made during development:

1. Organized by usage pattern rather than API method: Instead of documenting each SDK method alphabetically (select, insert, update, etc.), grouped references by how developers actually work - setting up clients, writing queries, handling errors, optimizing performance. This matches the mental model of building features rather than learning API surfaces.

2. Emphasized @supabase/ssr over deprecated packages: Explicitly called out that @supabase/auth-helpers-nextjs is deprecated and demonstrated correct patterns with @supabase/ssr. Used getAll()/setAll() cookie methods instead of individual cookie operations, which is the current best practice for Next.js 13+.

3. Focus on Incorrect/Correct pattern format: Each reference follows a consistent structure showing common mistakes first, then the correct approach. This addresses real pain points developers face (e.g., creating multiple client instances, forgetting error checks, missing subscription cleanup).

4. Separate browser vs server client patterns: Created distinct references for browser and server contexts because they use different packages (createBrowserClient vs createServerClient) and have different singleton/cookie requirements. This prevents confusion around when to use which approach.

5. Prioritized realtime cleanup patterns: Realtime subscription memory leaks are a common issue in React applications. Dedicated a full reference to proper cleanup with useEffect dependency handling and removeChannel() patterns.

6. Progressive disclosure from SKILL.md: Kept SKILL.md lean with just the resources table pointing to detailed SDK references. The body of SKILL.md focuses on core concepts, while SDK-specific patterns live in dedicated reference files that load on demand.

Additional context

Sources consulted:

• Supabase official documentation (initializing, server-side auth, type generation, filters, joins, realtime)
• Supabase MCP search_docs tool for latest patterns and best practices
• Next.js 13+ App Router patterns for SSR integration

Framework focus:
Started with Next.js App Router as the primary framework example since it represents the current best practice for React SSR. Future PRs could add framework-specific references for Remix, SvelteKit, Nuxt, etc.

Type safety emphasis:
TypeScript type generation is marked HIGH impact because it provides compile-time safety for all database operations. The workflow includes CLI commands for both local and remote type generation, plus CI/CD integration patterns.

Realtime scale considerations:
Documented the single-thread limitation of Postgres Changes and recommended using Broadcast for high-throughput scenarios. Included filter patterns to reduce server load by filtering at the source.