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.
Install this agent skill to your Project
npx add-skill https://github.com/Spectaculous-Code/raamattu-nyt/tree/main/.claude/skills/supabase-typing-architect
SKILL.md
Supabase Typing Architect
Diagnose and fix Supabase TypeScript typing issues. Act as diagnostician + surgeon, not general builder.
Cross-cutting learnings: See .claude/LEARNINGS.md → "Supabase Type Casts" section for as any patterns, when to regenerate types, and proper casting techniques.
Golden Rules
- NEVER modify auto-generated
types.ts- It gets overwritten bysupabase gen types - NEVER add
as anyunless explicitly requested by user - NEVER duplicate the
Databasetype - Extend it, don't copy it - 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:
// 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:
// 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:
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:
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:
- Regenerate:
npx supabase gen types typescript --project-id xxx > types.ts - Move custom types to custom-types.ts
- Update imports
Issue: Lovable preview can't resolve types
Fix: Ensure vite.config.ts has:
resolve: {
alias: {
'@': path.resolve(__dirname, './src'),
},
},
Type Regeneration
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
- references/type-inventory.md - Complete type source inventory
- references/rpc-type-map.md - RPC function signatures
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
docs-updater
Expert assistant for keeping documentation synchronized with code changes in the KR92 Bible Voice project. Use when updating API docs, maintaining architecture diagrams, syncing README, updating CLAUDE.MD, or generating documentation from code.
ai-prompt-manager
Expert assistant for managing AI prompts, features, and configuration in the KR92 Bible Voice AI system. Use when creating AI prompts, configuring AI features, managing prompt versions, setting up AI bindings, or working with AI pricing and models.
performance-auditor
Expert assistant for monitoring and optimizing performance in the KR92 Bible Voice project. Use when analyzing query performance, optimizing database indexes, reviewing React Query caching, monitoring AI call costs, or identifying N+1 queries.
edge-function-generator
Expert assistant for creating and maintaining Supabase Edge Functions for the KR92 Bible Voice project. Use when creating Edge Functions, setting up CORS, integrating shared modules, adding JWT validation, or configuring environment variables.
admin-panel-builder
Expert assistant for creating and maintaining admin panel pages in the KR92 Bible Voice project. Use when creating admin pages, building admin components, integrating with admin navigation, or adding admin features.
lint-fixer
Expert assistant for analyzing and fixing linting and formatting issues in the KR92 Bible Voice project using Biome and TypeScript. Use when fixing lint errors, resolving TypeScript issues, applying code formatting, or reviewing code quality.
Didn't find tool you were looking for?