@intentsolutionsio/supabase-pack 1.0.0 → 1.0.3

package/skills/supabase-architecture-variants/SKILL.md

@@ -1,284 +1,463 @@
 ---
 name: supabase-architecture-variants
-description: |
-  Choose and implement Supabase validated architecture blueprints for different scales.
-  Use when designing new Supabase integrations, choosing between monolith/service/microservice
-  architectures, or planning migration paths for Supabase applications.
-  Trigger with phrases like "supabase architecture", "supabase blueprint",
-  "how to structure supabase", "supabase project layout", "supabase microservice".
-allowed-tools: Read, Grep
+description: 'Implement Supabase across different app architectures: Next.js SSR with
+
+  server components using service_role and client components with anon key,
+
+  SPA (React/Vue), mobile (React Native), serverless (Edge Functions),
+
+  and multi-tenant with schema-per-tenant or RLS isolation.
+
+  Use when choosing how to integrate Supabase into your specific stack,
+
+  setting up SSR auth flows, configuring mobile deep links,
+
+  or designing multi-tenant data isolation.
+
+  Trigger with phrases like "supabase next.js", "supabase SSR",
+
+  "supabase react native", "supabase SPA", "supabase serverless",
+
+  "supabase multi-tenant", "supabase server component",
+
+  "supabase architecture", "supabase service_role server".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(supabase:*), Bash(npx:*), Grep
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- supabase
+- architecture
+- nextjs
+- ssr
+- spa
+- mobile
+- multi-tenant
+- serverless
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Supabase Architecture Variants
 
 ## Overview
-Three validated architecture blueprints for Supabase integrations.
+
+Different application architectures require fundamentally different Supabase `createClient` configurations. The critical distinction is **where the client runs** (browser vs server) and **which key it uses** (anon key respects RLS; service_role bypasses it). This skill provides production-ready patterns for five architectures: **Next.js SSR** (server components with service_role, client components with anon), **SPA** (React/Vue with browser-only client), **Mobile** (React Native with deep link auth), **Serverless** (Edge Functions with per-request clients), and **Multi-tenant** (RLS-based or schema-per-tenant isolation).
 
 ## Prerequisites
-- Understanding of team size and DAU requirements
-- Knowledge of deployment infrastructure
-- Clear SLA requirements
-- Growth projections available
 
-## Variant A: Monolith (Simple)
+- `@supabase/supabase-js` v2+ installed
+- `@supabase/ssr` package for Next.js SSR (v0.5+)
+- Supabase project with URL, anon key, and service role key
+- TypeScript project with generated database types (`supabase gen types typescript`)
+- For mobile: React Native with Expo or bare workflow
 
-**Best for:** MVPs, small teams, < 10K daily active users
+## Step 1 — Next.js SSR (App Router with Server and Client Components)
 
-```
-my-app/
-├── src/
-│   ├── supabase/
-│   │   ├── client.ts          # Singleton client
-│   │   ├── types.ts           # Types
-│   │   └── middleware.ts      # Express middleware
-│   ├── routes/
-│   │   └── api/
-│   │       └── supabase.ts    # API routes
-│   └── index.ts
-├── tests/
-│   └── supabase.test.ts
-└── package.json
-```
+Next.js App Router requires **two separate clients**: a server-side client using cookies for auth (with `@supabase/ssr`) and a browser client for client components. Never expose `service_role` to the client.
 
-### Key Characteristics
-- Single deployment unit
-- Synchronous Supabase calls in request path
-- In-memory caching
-- Simple error handling
+### Server-Side Client (for Server Components, Route Handlers, Server Actions)
 
-### Code Pattern
 ```typescript
-// Direct integration in route handler
-app.post('/api/create', async (req, res) => {
-  try {
-    const result = await supabaseClient.create(req.body);
-    res.json(result);
-  } catch (error) {
-    res.status(500).json({ error: error.message });
-  }
-});
+// lib/supabase/server.ts
+import { createServerClient } from '@supabase/ssr'
+import { cookies } from 'next/headers'
+import type { Database } from '../database.types'
+
+export async function createSupabaseServer() {
+  const cookieStore = await cookies()
+
+  return createServerClient<Database>(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() {
+          return cookieStore.getAll()
+        },
+        setAll(cookiesToSet) {
+          try {
+            cookiesToSet.forEach(({ name, value, options }) =>
+              cookieStore.set(name, value, options)
+            )
+          } catch {
+            // Called from Server Component — cookies are read-only
+          }
+        },
+      },
+    }
+  )
+}
+
+// Admin client for server-only operations (bypasses RLS)
+// NEVER import this in client components or expose to the browser
+import { createClient } from '@supabase/supabase-js'
+
+export function createSupabaseAdmin() {
+  return createClient<Database>(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.SUPABASE_SERVICE_ROLE_KEY!,  // NOT NEXT_PUBLIC_ — server only
+    {
+      auth: { autoRefreshToken: false, persistSession: false },
+    }
+  )
+}
 ```
 
----
+### Client-Side Client (for Client Components)
+
+```typescript
+// lib/supabase/client.ts
+'use client'
+
+import { createBrowserClient } from '@supabase/ssr'
+import type { Database } from '../database.types'
+
+let client: ReturnType<typeof createBrowserClient<Database>> | null = null
 
-## Variant B: Service Layer (Moderate)
+export function createSupabaseBrowser() {
+  if (client) return client
 
-**Best for:** Growing startups, 10K-100K DAU, multiple integrations
+  client = createBrowserClient<Database>(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!  // anon key only — respects RLS
+  )
 
+  return client
+}
 ```
-my-app/
-├── src/
-│   ├── services/
-│   │   ├── supabase/
-│   │   │   ├── client.ts      # Client wrapper
-│   │   │   ├── service.ts     # Business logic
-│   │   │   ├── repository.ts  # Data access
-│   │   │   └── types.ts
-│   │   └── index.ts           # Service exports
-│   ├── controllers/
-│   │   └── supabase.ts
-│   ├── routes/
-│   ├── middleware/
-│   ├── queue/
-│   │   └── supabase-processor.ts  # Async processing
-│   └── index.ts
-├── config/
-│   └── supabase/
-└── package.json
+
+### Middleware for Auth Session Refresh
+
+```typescript
+// middleware.ts
+import { createServerClient } from '@supabase/ssr'
+import { NextResponse, type NextRequest } from 'next/server'
+
+export async function middleware(request: NextRequest) {
+  let response = NextResponse.next({ request })
+
+  const supabase = createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() {
+          return request.cookies.getAll()
+        },
+        setAll(cookiesToSet) {
+          cookiesToSet.forEach(({ name, value }) =>
+            request.cookies.set(name, value)
+          )
+          response = NextResponse.next({ request })
+          cookiesToSet.forEach(({ name, value, options }) =>
+            response.cookies.set(name, value, options)
+          )
+        },
+      },
+    }
+  )
+
+  // Refresh session — this is the critical call
+  await supabase.auth.getUser()
+
+  return response
+}
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)'],
+}
 ```
 
-### Key Characteristics
-- Separation of concerns
-- Background job processing
-- Redis caching
-- Circuit breaker pattern
-- Structured error handling
+### Server Component Usage
 
-### Code Pattern
 ```typescript
-// Service layer abstraction
-class SupabaseService {
-  constructor(
-    private client: SupabaseClient,
-    private cache: CacheService,
-    private queue: QueueService
-  ) {}
-
-  async createResource(data: CreateInput): Promise<Resource> {
-    // Business logic before API call
-    const validated = this.validate(data);
-
-    // Check cache
-    const cached = await this.cache.get(cacheKey);
-    if (cached) return cached;
-
-    // API call with retry
-    const result = await this.withRetry(() =>
-      this.client.create(validated)
-    );
-
-    // Cache result
-    await this.cache.set(cacheKey, result, 300);
-
-    // Async follow-up
-    await this.queue.enqueue('supabase.post-create', result);
-
-    return result;
-  }
+// app/dashboard/page.tsx
+import { createSupabaseServer } from '@/lib/supabase/server'
+import { redirect } from 'next/navigation'
+
+export default async function DashboardPage() {
+  const supabase = await createSupabaseServer()
+
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) redirect('/login')
+
+  const { data: projects, error } = await supabase
+    .from('projects')
+    .select('id, name, status, created_at')
+    .eq('user_id', user.id)
+    .order('created_at', { ascending: false })
+
+  if (error) throw new Error(`Failed to load projects: ${error.message}`)
+
+  return (
+    <div>
+      <h1>My Projects</h1>
+      {projects.map(p => <ProjectCard key={p.id} project={p} />)}
+    </div>
+  )
 }
 ```
 
----
+### Server Action with Admin Client
 
-## Variant C: Microservice (Complex)
+```typescript
+// app/actions/admin.ts
+'use server'
 
-**Best for:** Enterprise, 100K+ DAU, strict SLAs
+import { createSupabaseAdmin } from '@/lib/supabase/server'
 
-```
-supabase-service/              # Dedicated microservice
-├── src/
-│   ├── api/
-│   │   ├── grpc/
-│   │   │   └── supabase.proto
-│   │   └── rest/
-│   │       └── routes.ts
-│   ├── domain/
-│   │   ├── entities/
-│   │   ├── events/
-│   │   └── services/
-│   ├── infrastructure/
-│   │   ├── supabase/
-│   │   │   ├── client.ts
-│   │   │   ├── mapper.ts
-│   │   │   └── circuit-breaker.ts
-│   │   ├── cache/
-│   │   ├── queue/
-│   │   └── database/
-│   └── index.ts
-├── config/
-├── k8s/
-│   ├── deployment.yaml
-│   ├── service.yaml
-│   └── hpa.yaml
-└── package.json
-
-other-services/
-├── order-service/       # Calls supabase-service
-├── payment-service/
-└── notification-service/
+export async function deleteUserAccount(userId: string) {
+  const supabase = createSupabaseAdmin()
+
+  // Admin operation — bypasses RLS
+  const { error: deleteError } = await supabase
+    .from('user_data')
+    .delete()
+    .eq('user_id', userId)
+
+  if (deleteError) throw new Error(`Data deletion failed: ${deleteError.message}`)
+
+  // Delete auth user
+  const { error: authError } = await supabase.auth.admin.deleteUser(userId)
+  if (authError) throw new Error(`Auth deletion failed: ${authError.message}`)
+}
 ```
 
-### Key Characteristics
-- Dedicated Supabase microservice
-- gRPC for internal communication
-- Event-driven architecture
-- Database per service
-- Kubernetes autoscaling
-- Distributed tracing
-- Circuit breaker per service
+## Step 2 — SPA (React/Vue) and Mobile (React Native)
 
-### Code Pattern
-```typescript
-// Event-driven with domain isolation
-class SupabaseAggregate {
-  private events: DomainEvent[] = [];
+### SPA Architecture (React with Vite)
 
-  process(command: SupabaseCommand): void {
-    // Domain logic
-    const result = this.execute(command);
+SPAs use a single browser client with the anon key. All authorization is enforced via RLS. The service_role key is never present in the SPA bundle.
 
-    // Emit domain event
-    this.events.push(new SupabaseProcessedEvent(result));
+```typescript
+// src/lib/supabase.ts
+import { createClient } from '@supabase/supabase-js'
+import type { Database } from './database.types'
+
+// Singleton client — one instance for the entire SPA
+export const supabase = createClient<Database>(
+  import.meta.env.VITE_SUPABASE_URL,
+  import.meta.env.VITE_SUPABASE_ANON_KEY,
+  {
+    auth: {
+      autoRefreshToken: true,
+      persistSession: true,
+      detectSessionInUrl: true,  // handles OAuth redirects
+      storage: window.localStorage,
+    },
   }
+)
 
-  getUncommittedEvents(): DomainEvent[] {
-    return [...this.events];
+// Auth state listener — call once at app initialization
+supabase.auth.onAuthStateChange((event, session) => {
+  if (event === 'SIGNED_OUT') {
+    // Clear local caches
+    queryClient.clear()  // React Query
   }
-}
-
-// Event handler
-@EventHandler(SupabaseProcessedEvent)
-class SupabaseEventHandler {
-  async handle(event: SupabaseProcessedEvent): Promise<void> {
-    // Saga orchestration
-    await this.sagaOrchestrator.continue(event);
+  if (event === 'TOKEN_REFRESHED') {
+    console.log('Token refreshed')
   }
-}
+})
 ```
 
----
+### React Hook for Auth-Protected Queries
+
+```typescript
+// src/hooks/useSupabaseQuery.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { supabase } from '../lib/supabase'
+
+export function useTodos() {
+  return useQuery({
+    queryKey: ['todos'],
+    queryFn: async () => {
+      const { data, error } = await supabase
+        .from('todos')
+        .select('id, title, is_complete, created_at')
+        .order('created_at', { ascending: false })
+
+      if (error) throw new Error(`Failed to load todos: ${error.message}`)
+      return data
+    },
+  })
+}
 
-## Decision Matrix
+export function useCreateTodo() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (title: string) => {
+      const { data, error } = await supabase
+        .from('todos')
+        .insert({ title })
+        .select('id, title, is_complete, created_at')
+        .single()
+
+      if (error) throw new Error(`Failed to create todo: ${error.message}`)
+      return data
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+}
+```
 
-| Factor | Monolith | Service Layer | Microservice |
-|--------|----------|---------------|--------------|
-| Team Size | 1-5 | 5-20 | 20+ |
-| DAU | < 10K | 10K-100K | 100K+ |
-| Deployment Frequency | Weekly | Daily | Continuous |
-| Failure Isolation | None | Partial | Full |
-| Operational Complexity | Low | Medium | High |
-| Time to Market | Fastest | Moderate | Slowest |
+### Mobile Architecture (React Native with Expo)
 
-## Migration Path
+React Native needs `AsyncStorage` for session persistence and deep link handling for OAuth.
 
-```
-Monolith → Service Layer:
-1. Extract Supabase code to service/
-2. Add caching layer
-3. Add background processing
-
-Service Layer → Microservice:
-1. Create dedicated supabase-service repo
-2. Define gRPC contract
-3. Add event bus
-4. Deploy to Kubernetes
-5. Migrate traffic gradually
+```typescript
+// lib/supabase.ts (React Native)
+import { createClient } from '@supabase/supabase-js'
+import AsyncStorage from '@react-native-async-storage/async-storage'
+import type { Database } from './database.types'
+
+export const supabase = createClient<Database>(
+  process.env.EXPO_PUBLIC_SUPABASE_URL!,
+  process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY!,
+  {
+    auth: {
+      storage: AsyncStorage,
+      autoRefreshToken: true,
+      persistSession: true,
+      detectSessionInUrl: false,  // disabled for React Native
+    },
+  }
+)
 ```
 
-## Instructions
+### Mobile OAuth with Deep Links
 
-### Step 1: Assess Requirements
-Use the decision matrix to identify appropriate variant.
+```typescript
+// lib/auth.ts (React Native)
+import { supabase } from './supabase'
+import * as Linking from 'expo-linking'
+import * as WebBrowser from 'expo-web-browser'
+
+const redirectUrl = Linking.createURL('auth/callback')
+
+export async function signInWithGoogle() {
+  const { data, error } = await supabase.auth.signInWithOAuth({
+    provider: 'google',
+    options: {
+      redirectTo: redirectUrl,
+      skipBrowserRedirect: true,  // handle manually for RN
+    },
+  })
+
+  if (error) throw new Error(`OAuth failed: ${error.message}`)
+  if (!data.url) throw new Error('No OAuth URL returned')
+
+  // Open in-app browser
+  const result = await WebBrowser.openAuthSessionAsync(data.url, redirectUrl)
+
+  if (result.type === 'success') {
+    const url = new URL(result.url)
+    const params = new URLSearchParams(url.hash.substring(1))
+    const accessToken = params.get('access_token')
+    const refreshToken = params.get('refresh_token')
+
+    if (accessToken && refreshToken) {
+      const { error: sessionError } = await supabase.auth.setSession({
+        access_token: accessToken,
+        refresh_token: refreshToken,
+      })
+      if (sessionError) throw sessionError
+    }
+  }
+}
+```
 
-### Step 2: Choose Architecture
-Select Monolith, Service Layer, or Microservice based on needs.
+### App.json Deep Link Configuration (Expo)
+
+```json
+{
+  "expo": {
+    "scheme": "myapp",
+    "plugins": [
+      [
+        "expo-linking",
+        {
+          "scheme": "myapp"
+        }
+      ]
+    ]
+  }
+}
+```
 
-### Step 3: Implement Structure
-Set up project layout following the chosen blueprint.
+## Step 3 — Serverless (Edge Functions) and Multi-Tenant
 
-### Step 4: Plan Migration Path
-Document upgrade path for future scaling.
+See [serverless and multi-tenant patterns](references/serverless-and-multi-tenant.md) for Edge Function per-request clients, admin operation escalation, RLS-based multi-tenant isolation with schema, and tenant-scoped SDK queries.
 
 ## Output
-- Architecture variant selected
-- Project structure implemented
-- Migration path documented
-- Appropriate patterns applied
+
+- Next.js SSR setup with server client (cookies-based auth), browser client, and middleware
+- Server Actions using admin client with service_role for privileged operations
+- SPA pattern with singleton client, React Query integration, and auth state listener
+- React Native setup with AsyncStorage, deep link OAuth, and in-app browser
+- Edge Function patterns for per-request auth and admin escalation
+- Multi-tenant RLS isolation with tenant_members lookup and scoped queries
+- Decision matrix for choosing the right architecture per stack
 
 ## Error Handling
+
 | Issue | Cause | Solution |
 |-------|-------|----------|
-| Over-engineering | Wrong variant choice | Start simpler |
-| Performance issues | Wrong layer | Add caching/async |
-| Team friction | Complex architecture | Simplify or train |
-| Deployment complexity | Microservice overhead | Consider service layer |
+| `AuthSessionMissingError` in Server Component | Cookies not passed to Supabase client | Use `createServerClient` from `@supabase/ssr` with cookie handlers |
+| OAuth redirect fails in React Native | Missing deep link scheme | Add `scheme` to app.json and configure Supabase redirect URL |
+| service_role key in client bundle | Wrong env var prefix (`NEXT_PUBLIC_`) | Remove `NEXT_PUBLIC_` prefix; only server code should access it |
+| Multi-tenant data leak | Missing RLS policy or missing tenant_id filter | Verify RLS is enabled and policies check `tenant_members` |
+| Edge Function `auth.getUser()` returns null | Missing Authorization header | Forward user's JWT from the client call |
+| Session not persisting on mobile | AsyncStorage not configured | Pass `AsyncStorage` in auth config; ensure package is installed |
 
 ## Examples
 
-### Quick Variant Check
-```bash
-# Count team size and DAU to select variant
-echo "Team: $(git log --format='%ae' | sort -u | wc -l) developers"
-echo "DAU: Check analytics dashboard"
+### Test Auth Flow End-to-End (Next.js)
+
+```typescript
+// app/auth/callback/route.ts
+import { createSupabaseServer } from '@/lib/supabase/server'
+import { NextResponse } from 'next/server'
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url)
+  const code = searchParams.get('code')
+
+  if (code) {
+    const supabase = await createSupabaseServer()
+    const { error } = await supabase.auth.exchangeCodeForSession(code)
+    if (error) {
+      return NextResponse.redirect(new URL('/login?error=auth_failed', request.url))
+    }
+  }
+
+  return NextResponse.redirect(new URL('/dashboard', request.url))
+}
+```
+
+### Verify Tenant Isolation
+
+```sql
+-- Test that RLS properly isolates tenants
+SET request.jwt.claims = '{"sub": "user-uuid-1"}';
+
+-- Should only return projects for user-uuid-1's tenant
+SELECT * FROM public.projects;
 ```
 
 ## Resources
-- [Monolith First](https://martinfowler.com/bliki/MonolithFirst.html)
-- [Microservices Guide](https://martinfowler.com/microservices/)
-- [Supabase Architecture Guide](https://supabase.com/docs/architecture)
+
+- [Supabase SSR (Next.js)](https://supabase.com/docs/guides/auth/server-side/nextjs)
+- [Supabase React Native](https://supabase.com/docs/guides/getting-started/tutorials/with-expo-react-native)
+- [Supabase Edge Functions](https://supabase.com/docs/guides/functions)
+- [Multi-Tenant with RLS](https://supabase.com/docs/guides/database/postgres/row-level-security)
+- [Supabase Auth Deep Linking](https://supabase.com/docs/guides/auth/native-mobile-deep-linking)
+- [@supabase/ssr Package](https://supabase.com/docs/guides/auth/server-side/overview)
 
 ## Next Steps
-For common anti-patterns, see `supabase-known-pitfalls`.
+
+For common mistakes and anti-patterns to avoid, see `supabase-known-pitfalls`.