create-claude-webapp 1.0.0 → 1.0.2

package/.claude/skills/supabase-edge-functions/SKILL.md

@@ -0,0 +1,386 @@
+---
+name: supabase-edge-functions
+description: Supabase Edge Functions with Deno runtime. Use when creating serverless functions, webhooks, or API endpoints that run on Supabase Edge.
+---
+
+# Supabase Edge Functions
+
+## Function Structure
+
+### Directory Layout
+```
+supabase/
+  functions/
+    _shared/           # Shared code between functions
+      cors.ts
+      supabase.ts
+    function-name/
+      index.ts         # Entry point (required)
+    another-function/
+      index.ts
+```
+
+### Basic Function Template
+```typescript
+// supabase/functions/hello-world/index.ts
+import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
+
+serve(async (req: Request) => {
+  const { name } = await req.json()
+
+  return new Response(
+    JSON.stringify({ message: `Hello ${name}!` }),
+    {
+      headers: { 'Content-Type': 'application/json' },
+    }
+  )
+})
+```
+
+## Type Safety in Deno
+
+### Import Maps
+```json
+// supabase/functions/import_map.json
+{
+  "imports": {
+    "@supabase/supabase-js": "https://esm.sh/@supabase/supabase-js@2",
+    "shared/": "../_shared/"
+  }
+}
+```
+
+### Type Definitions
+```typescript
+// supabase/functions/_shared/types.ts
+export interface ApiResponse<T> {
+  data: T | null
+  error: string | null
+}
+
+export interface UserPayload {
+  userId: string
+  email: string
+  action: string
+}
+```
+
+### Using Types in Functions
+```typescript
+// supabase/functions/process-user/index.ts
+import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
+import type { UserPayload, ApiResponse } from 'shared/types.ts'
+
+serve(async (req: Request): Promise<Response> => {
+  try {
+    const payload: UserPayload = await req.json()
+
+    // Process...
+
+    const response: ApiResponse<{ processed: boolean }> = {
+      data: { processed: true },
+      error: null,
+    }
+
+    return new Response(JSON.stringify(response), {
+      headers: { 'Content-Type': 'application/json' },
+    })
+  } catch (error) {
+    const response: ApiResponse<null> = {
+      data: null,
+      error: error.message,
+    }
+
+    return new Response(JSON.stringify(response), {
+      status: 400,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+})
+```
+
+## Authentication in Edge Functions
+
+### Extracting User from JWT
+```typescript
+// supabase/functions/_shared/supabase.ts
+import { createClient } from '@supabase/supabase-js'
+
+export const getSupabaseClient = (authHeader: string | null) => {
+  return createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_ANON_KEY')!,
+    {
+      global: {
+        headers: authHeader ? { Authorization: authHeader } : {},
+      },
+    }
+  )
+}
+
+export const getUser = async (req: Request) => {
+  const authHeader = req.headers.get('Authorization')
+
+  if (!authHeader) {
+    return { user: null, error: 'No authorization header' }
+  }
+
+  const supabase = getSupabaseClient(authHeader)
+  const { data: { user }, error } = await supabase.auth.getUser()
+
+  return { user, error: error?.message ?? null }
+}
+```
+
+### Protected Function Example
+```typescript
+// supabase/functions/protected/index.ts
+import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
+import { getUser, getSupabaseClient } from 'shared/supabase.ts'
+import { corsHeaders } from 'shared/cors.ts'
+
+serve(async (req: Request) => {
+  // Handle CORS preflight
+  if (req.method === 'OPTIONS') {
+    return new Response('ok', { headers: corsHeaders })
+  }
+
+  const { user, error } = await getUser(req)
+
+  if (error || !user) {
+    return new Response(
+      JSON.stringify({ error: 'Unauthorized' }),
+      { status: 401, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
+    )
+  }
+
+  // User is authenticated, proceed with logic
+  const supabase = getSupabaseClient(req.headers.get('Authorization'))
+
+  const { data, error: dbError } = await supabase
+    .from('user_data')
+    .select('*')
+    .eq('user_id', user.id)
+
+  return new Response(
+    JSON.stringify({ data }),
+    { headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
+  )
+})
+```
+
+### Service Role Access
+```typescript
+// For admin operations, use service role key
+import { createClient } from '@supabase/supabase-js'
+
+const supabaseAdmin = createClient(
+  Deno.env.get('SUPABASE_URL')!,
+  Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
+)
+
+// Bypasses RLS
+const { data } = await supabaseAdmin.from('users').select('*')
+```
+
+## CORS Handling
+
+### Shared CORS Configuration
+```typescript
+// supabase/functions/_shared/cors.ts
+export const corsHeaders = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
+}
+
+export const handleCors = (req: Request): Response | null => {
+  if (req.method === 'OPTIONS') {
+    return new Response('ok', { headers: corsHeaders })
+  }
+  return null
+}
+```
+
+### Using CORS in Functions
+```typescript
+import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
+import { corsHeaders, handleCors } from 'shared/cors.ts'
+
+serve(async (req: Request) => {
+  const corsResponse = handleCors(req)
+  if (corsResponse) return corsResponse
+
+  // Function logic...
+
+  return new Response(
+    JSON.stringify({ success: true }),
+    { headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
+  )
+})
+```
+
+## Local Development
+
+### Running Functions Locally
+```bash
+# Start all functions
+supabase functions serve
+
+# Start specific function
+supabase functions serve hello-world
+
+# With environment variables
+supabase functions serve --env-file .env.local
+```
+
+### Testing Locally
+```bash
+# Invoke function
+curl -i --location --request POST 'http://127.0.0.1:54321/functions/v1/hello-world' \
+  --header 'Authorization: Bearer YOUR_ANON_KEY' \
+  --header 'Content-Type: application/json' \
+  --data '{"name": "World"}'
+```
+
+## Deployment
+
+### Deploy Single Function
+```bash
+supabase functions deploy hello-world
+```
+
+### Deploy All Functions
+```bash
+supabase functions deploy
+```
+
+### Setting Secrets
+```bash
+# Set secret
+supabase secrets set MY_SECRET=value
+
+# List secrets
+supabase secrets list
+
+# Unset secret
+supabase secrets unset MY_SECRET
+```
+
+## Webhooks Pattern
+
+### Database Webhook Handler
+```typescript
+// supabase/functions/on-user-created/index.ts
+import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
+
+interface WebhookPayload {
+  type: 'INSERT' | 'UPDATE' | 'DELETE'
+  table: string
+  record: Record<string, unknown>
+  schema: string
+  old_record: Record<string, unknown> | null
+}
+
+serve(async (req: Request) => {
+  const payload: WebhookPayload = await req.json()
+
+  if (payload.type === 'INSERT' && payload.table === 'users') {
+    // Send welcome email, create related records, etc.
+    console.log('New user created:', payload.record)
+  }
+
+  return new Response(JSON.stringify({ received: true }), {
+    headers: { 'Content-Type': 'application/json' },
+  })
+})
+```
+
+### Setting Up Database Webhook
+```sql
+-- In Supabase Studio or migration
+CREATE OR REPLACE FUNCTION notify_user_created()
+RETURNS trigger AS $$
+BEGIN
+  PERFORM net.http_post(
+    url := 'https://YOUR_PROJECT.supabase.co/functions/v1/on-user-created',
+    headers := '{"Authorization": "Bearer ' || current_setting('app.service_role_key') || '"}'::jsonb,
+    body := jsonb_build_object(
+      'type', TG_OP,
+      'table', TG_TABLE_NAME,
+      'record', row_to_json(NEW),
+      'old_record', row_to_json(OLD)
+    )
+  );
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER on_user_created
+  AFTER INSERT ON users
+  FOR EACH ROW
+  EXECUTE FUNCTION notify_user_created();
+```
+
+## Environment Variables
+
+### Available by Default
+| Variable | Description |
+|----------|-------------|
+| `SUPABASE_URL` | Project URL |
+| `SUPABASE_ANON_KEY` | Anon/public key |
+| `SUPABASE_SERVICE_ROLE_KEY` | Service role key |
+| `SUPABASE_DB_URL` | Direct database connection |
+
+### Accessing Environment Variables
+```typescript
+const supabaseUrl = Deno.env.get('SUPABASE_URL')!
+const customSecret = Deno.env.get('MY_CUSTOM_SECRET')!
+```
+
+## Error Handling Best Practices
+
+```typescript
+serve(async (req: Request) => {
+  try {
+    // Validate request method
+    if (req.method !== 'POST') {
+      return new Response(
+        JSON.stringify({ error: 'Method not allowed' }),
+        { status: 405, headers: { 'Content-Type': 'application/json' } }
+      )
+    }
+
+    // Validate content type
+    const contentType = req.headers.get('content-type')
+    if (!contentType?.includes('application/json')) {
+      return new Response(
+        JSON.stringify({ error: 'Content-Type must be application/json' }),
+        { status: 400, headers: { 'Content-Type': 'application/json' } }
+      )
+    }
+
+    // Parse and validate body
+    const body = await req.json()
+    if (!body.requiredField) {
+      return new Response(
+        JSON.stringify({ error: 'requiredField is required' }),
+        { status: 400, headers: { 'Content-Type': 'application/json' } }
+      )
+    }
+
+    // Process...
+    return new Response(
+      JSON.stringify({ success: true }),
+      { headers: { 'Content-Type': 'application/json' } }
+    )
+
+  } catch (error) {
+    console.error('Function error:', error)
+
+    return new Response(
+      JSON.stringify({ error: 'Internal server error' }),
+      { status: 500, headers: { 'Content-Type': 'application/json' } }
+    )
+  }
+})
+```

package/.claude/skills/supabase-local/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: supabase-local
+description: Local Supabase development with CLI, migrations, and seeding. Use when setting up local development environment, running migrations, or managing local Supabase instance.
+---
+
+# Supabase Local Development
+
+## CLI Commands Reference
+
+### Essential Commands
+
+| Command | Purpose |
+|---------|---------|
+| `supabase start` | Start local Supabase stack |
+| `supabase stop` | Stop local Supabase stack |
+| `supabase status` | Show running services and URLs |
+| `supabase db reset` | Reset database and apply migrations |
+| `supabase db diff` | Generate migration from schema changes |
+| `supabase db push` | Push migrations to remote |
+
+### Starting Local Development
+```bash
+# Initialize Supabase in project (first time)
+supabase init
+
+# Start local stack
+supabase start
+
+# Output includes local URLs and keys:
+# API URL: http://127.0.0.1:54321
+# GraphQL URL: http://127.0.0.1:54321/graphql/v1
+# DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
+# Studio URL: http://127.0.0.1:54323
+# Inbucket URL: http://127.0.0.1:54324
+# anon key: eyJ...
+# service_role key: eyJ...
+```
+
+### Stopping and Resetting
+```bash
+# Stop (preserves data)
+supabase stop
+
+# Stop and reset all data
+supabase stop --no-backup
+
+# Reset database (reapply all migrations + seed)
+supabase db reset
+```
+
+## Local Configuration
+
+### config.toml Structure
+```toml
+# supabase/config.toml
+
+[api]
+enabled = true
+port = 54321
+schemas = ["public", "graphql_public"]
+extra_search_path = ["public", "extensions"]
+max_rows = 1000
+
+[db]
+port = 54322
+shadow_port = 54320
+major_version = 15
+
+[studio]
+enabled = true
+port = 54323
+api_url = "http://127.0.0.1"
+
+[inbucket]
+enabled = true
+port = 54324
+smtp_port = 54325
+pop3_port = 54326
+
+[auth]
+enabled = true
+site_url = "http://127.0.0.1:3000"
+additional_redirect_urls = ["https://127.0.0.1:3000"]
+jwt_expiry = 3600
+enable_signup = true
+enable_anonymous_sign_ins = false
+
+[auth.email]
+enable_signup = true
+double_confirm_changes = true
+enable_confirmations = false
+
+[auth.sms]
+enable_signup = false
+enable_confirmations = false
+
+[storage]
+enabled = true
+file_size_limit = "50MiB"
+
+[edge_runtime]
+enabled = true
+policy = "per_worker"
+inspector_port = 8083
+
+[analytics]
+enabled = false
+port = 54327
+vector_port = 54328
+```
+
+### Port Allocation Summary
+
+| Service | Default Port |
+|---------|-------------|
+| API | 54321 |
+| Database | 54322 |
+| Studio | 54323 |
+| Inbucket | 54324 |
+| SMTP | 54325 |
+| POP3 | 54326 |
+| Analytics | 54327 |
+
+## Migration Workflow
+
+### Creating Migrations
+
+**Option 1: Manual Creation**
+```bash
+# Create empty migration file
+supabase migration new create_users_table
+
+# Edit: supabase/migrations/TIMESTAMP_create_users_table.sql
+```
+
+**Option 2: Generate from Schema Changes**
+```bash
+# Make changes in Studio, then:
+supabase db diff -f add_avatar_to_users
+
+# Creates: supabase/migrations/TIMESTAMP_add_avatar_to_users.sql
+```
+
+**Option 3: Pull from Remote**
+```bash
+# Pull schema from remote project
+supabase db pull
+
+# Creates migration files from remote schema
+```
+
+### Applying Migrations
+```bash
+# Apply to local
+supabase db reset  # Resets and applies all migrations
+
+# Push to remote
+supabase db push
+```
+
+### Migration File Example
+```sql
+-- supabase/migrations/20240115120000_create_users_table.sql
+
+-- Create users table
+CREATE TABLE public.users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email TEXT UNIQUE NOT NULL,
+  name TEXT,
+  avatar_url TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Enable RLS
+ALTER TABLE public.users ENABLE ROW LEVEL SECURITY;
+
+-- Create policies
+CREATE POLICY "Users can view own profile"
+  ON public.users FOR SELECT
+  TO authenticated
+  USING (auth.uid() = id);
+
+CREATE POLICY "Users can update own profile"
+  ON public.users FOR UPDATE
+  TO authenticated
+  USING (auth.uid() = id)
+  WITH CHECK (auth.uid() = id);
+
+-- Create updated_at trigger
+CREATE OR REPLACE FUNCTION update_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = now();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER update_users_updated_at
+  BEFORE UPDATE ON public.users
+  FOR EACH ROW
+  EXECUTE FUNCTION update_updated_at();
+```
+
+## Seeding Data
+
+### Seed File Location
+```
+supabase/seed.sql
+```
+
+### Seed File Example
+```sql
+-- supabase/seed.sql
+
+-- Insert test users (for development only)
+INSERT INTO auth.users (id, email, encrypted_password, email_confirmed_at)
+VALUES
+  ('d0d8c4c0-0000-0000-0000-000000000001', 'alice@example.com', crypt('password123', gen_salt('bf')), now()),
+  ('d0d8c4c0-0000-0000-0000-000000000002', 'bob@example.com', crypt('password123', gen_salt('bf')), now());
+
+-- Insert corresponding profiles
+INSERT INTO public.users (id, email, name)
+VALUES
+  ('d0d8c4c0-0000-0000-0000-000000000001', 'alice@example.com', 'Alice'),
+  ('d0d8c4c0-0000-0000-0000-000000000002', 'bob@example.com', 'Bob');
+
+-- Insert sample data
+INSERT INTO public.posts (id, user_id, title, content, published)
+VALUES
+  (gen_random_uuid(), 'd0d8c4c0-0000-0000-0000-000000000001', 'First Post', 'Hello World!', true),
+  (gen_random_uuid(), 'd0d8c4c0-0000-0000-0000-000000000002', 'Another Post', 'Testing...', false);
+```
+
+### Running Seeds
+```bash
+# Seeds run automatically on db reset
+supabase db reset
+
+# Or manually
+psql -h 127.0.0.1 -p 54322 -U postgres -d postgres -f supabase/seed.sql
+```
+
+## Local vs Production Parity
+
+### Environment-Specific Configurations
+
+| Setting | Local | Production |
+|---------|-------|------------|
+| Email confirmation | Disabled | Enabled |
+| JWT expiry | 3600s (testing) | 3600s+ (security) |
+| Anonymous sign-ins | Disabled | As needed |
+| SMTP | Inbucket (fake) | Real provider |
+
+### Testing Email Locally
+```bash
+# Emails captured in Inbucket
+# Access: http://127.0.0.1:54324
+
+# No real emails sent in local development
+```
+
+### Environment Variables for Local
+```env
+# .env.local
+NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...  # From supabase start output
+```
+
+## Common Local Development Tasks
+
+### Inspect Database
+```bash
+# Connect to local database
+psql postgresql://postgres:postgres@127.0.0.1:54322/postgres
+
+# Or use Studio
+open http://127.0.0.1:54323
+```
+
+### View Logs
+```bash
+# All services
+supabase logs
+
+# Specific service
+supabase logs --api
+supabase logs --db
+supabase logs --auth
+```
+
+### Type Generation
+```bash
+# Generate types from local schema
+supabase gen types typescript --local > src/types/database.types.ts
+```
+
+## Troubleshooting
+
+### Port Conflicts
+```bash
+# Check what's using the port
+lsof -i :54321
+
+# Use different ports in config.toml
+[api]
+port = 54421
+```
+
+### Docker Issues
+```bash
+# Ensure Docker is running
+docker info
+
+# Reset Supabase Docker containers
+supabase stop --no-backup
+docker system prune -f
+supabase start
+```
+
+### Migration Conflicts
+```bash
+# If migrations are out of sync
+supabase db reset  # Local only
+
+# For remote, may need manual intervention
+supabase migration repair --status reverted MIGRATION_VERSION
+```