Agent skill

supabase-typing-architect

Supabase TypeScript typing specialist for multi-schema databases. Diagnoses and fixes type issues without touching business logic. Use when: - "Lovable ei näe Supabase-tyyppejä" (Lovable can't see Supabase types) - "RPC:t ei ole tyypitetty" (RPCs are not typed) - "Monorepo + Supabase types sekoilee" (monorepo type confusion) - "as any on levinnyt RPC-kutsuihin" (as any spreading in RPC calls) - "Types.ts löytyy mutta TS ei tunnista sitä" (types.ts exists but TS doesn't recognize it) - TypeScript errors on supabase.rpc() calls - Missing types for bible_schema, notifications, admin, or other non-public schemas - Import path issues with @/integrations/supabase/types NOT for: Writing business logic, creating components, general TypeScript help.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/supabase-typing-architect

SKILL.md

Supabase Typing Architect

Diagnose and fix Supabase TypeScript typing issues. Act as diagnostician + surgeon, not general builder.

Golden Rules

  1. NEVER modify auto-generated types.ts - It gets overwritten by supabase gen types
  2. NEVER add as any unless explicitly requested by user
  3. NEVER duplicate the Database type - Extend it, don't copy it
  4. ALWAYS use typed wrappers for non-public schema RPC calls

Project Type Sources

File Source Editable?
src/integrations/supabase/types.ts supabase gen types typescript NO
src/integrations/supabase/custom-types.ts Manual YES
src/integrations/supabase/client.ts Lovable scaffold Carefully

Schema Architecture

This project uses multiple Postgres schemas:

Schema Content In Generated Types?
public User data, app config YES
bible_schema Bible verses, topics, AI NO (PostgREST exposed)
notifications Push notification queue NO
admin Audit logs, widget analytics NO
feedback User feedback system NO
auth Supabase Auth (managed) Partial

Diagnostic Flow

Type error on RPC call?
├── RPC in public schema → Check types.ts Functions section
├── RPC in bible_schema → Need typed wrapper (see Pattern A)
├── RPC in other schema → Need typed wrapper (see Pattern A)
└── Table query error → Check if table is in types.ts

Import error?
├── @/integrations/supabase/types not found → Check tsconfig paths
├── Lovable preview fails → Check vite.config.ts resolve.alias
└── Monorepo package can't import → Check package.json exports

Solution Patterns

Pattern A: Typed RPC Wrapper (for non-public schemas)

When RPC functions exist in bible_schema or other non-public schemas:

typescript
// src/integrations/supabase/custom-types.ts

export interface GetVerseStudyDataParams {
  p_osis: string;
  p_version_code?: string;
}

export interface VerseStudyData {
  verse_id: string;
  text_content: string;
  book_name: string;
  chapter_number: number;
  verse_number: number;
}

// Usage with type assertion (safe because we control the RPC):
const { data } = await (supabase.rpc as any)('get_verse_study_data', params) as {
  data: VerseStudyData | null;
  error: Error | null
};

Pattern B: Schema-Specific Client Helper

For frequently-used non-public schema operations:

typescript
// src/lib/bibleSchemaClient.ts
import { supabase } from '@/integrations/supabase/client';

export async function callBibleSchemaRpc<T>(
  functionName: string,
  params: Record<string, unknown>
): Promise<{ data: T | null; error: Error | null }> {
  return (supabase.rpc as any)(functionName, params);
}

Pattern C: REST API with Schema Header

For direct table access in non-public schemas:

typescript
const response = await fetch(`${SUPABASE_REST_URL}/table_name`, {
  headers: {
    'Accept-Profile': 'bible_schema',
    'apikey': SUPABASE_PUBLISHABLE_KEY,
  },
});

Common Issues & Fixes

Issue: as any spreading in codebase

Diagnosis:

bash
grep -r "as any" src/ --include="*.ts" --include="*.tsx" | grep -i supabase

Fix: Replace each as any with proper typed wrapper (Pattern A or B)

Issue: Types regenerated, custom types lost

Fix:

  1. Regenerate: npx supabase gen types typescript --project-id xxx > types.ts
  2. Move custom types to custom-types.ts
  3. Update imports

Issue: Lovable preview can't resolve types

Fix: Ensure vite.config.ts has:

typescript
resolve: {
  alias: {
    '@': path.resolve(__dirname, './src'),
  },
},

Type Regeneration

bash
npx supabase gen types typescript --project-id iryqgmjauybluwnqhxbg > apps/raamattu-nyt/src/integrations/supabase/types.ts

Anti-Patterns

Don't Do Instead
Edit types.ts Add to custom-types.ts
Copy Database type Import and extend it
Use as any without comment Use typed wrapper with explicit return type
Create duplicate supabase clients Import from @/integrations/supabase/client

References

Didn't find tool you were looking for?

Be as detailed as possible for better results