Implement Supabase reference architecture with best-practice project layout. Use when designing new Supabase integrations, reviewing project structure, or establishing architecture standards for Supabase applications. Trigger with phrases like "supabase architecture", "supabase best practices", "supabase project structure", "how to organize supabase", "supabase layout".
/plugin marketplace add jeremylongshore/claude-code-plugins-plus-skills/plugin install supabase-pack@claude-code-plugins-plusThis skill is limited to using the following tools:
Production-ready architecture patterns for Supabase integrations.
my-supabase-project/
├── src/
│ ├── supabase/
│ │ ├── client.ts # Singleton client wrapper
│ │ ├── config.ts # Environment configuration
│ │ ├── types.ts # TypeScript types
│ │ ├── errors.ts # Custom error classes
│ │ └── handlers/
│ │ ├── webhooks.ts # Webhook handlers
│ │ └── events.ts # Event processing
│ ├── services/
│ │ └── supabase/
│ │ ├── index.ts # Service facade
│ │ ├── sync.ts # Data synchronization
│ │ └── cache.ts # Caching layer
│ ├── api/
│ │ └── supabase/
│ │ └── webhook.ts # Webhook endpoint
│ └── jobs/
│ └── supabase/
│ └── sync.ts # Background sync job
├── tests/
│ ├── unit/
│ │ └── supabase/
│ └── integration/
│ └── supabase/
├── config/
│ ├── supabase.development.json
│ ├── supabase.staging.json
│ └── supabase.production.json
└── docs/
└── supabase/
├── SETUP.md
└── RUNBOOK.md
┌─────────────────────────────────────────┐
│ API Layer │
│ (Controllers, Routes, Webhooks) │
├─────────────────────────────────────────┤
│ Service Layer │
│ (Business Logic, Orchestration) │
├─────────────────────────────────────────┤
│ Supabase Layer │
│ (Client, Types, Error Handling) │
├─────────────────────────────────────────┤
│ Infrastructure Layer │
│ (Cache, Queue, Monitoring) │
└─────────────────────────────────────────┘
// src/supabase/client.ts
export class SupabaseService {
private client: SupabaseClient;
private cache: Cache;
private monitor: Monitor;
constructor(config: SupabaseConfig) {
this.client = new SupabaseClient(config);
this.cache = new Cache(config.cacheOptions);
this.monitor = new Monitor('supabase');
}
async get(id: string): Promise<Resource> {
return this.cache.getOrFetch(id, () =>
this.monitor.track('get', () => this.client.get(id))
);
}
}
// src/supabase/errors.ts
export class SupabaseServiceError extends Error {
constructor(
message: string,
public readonly code: string,
public readonly retryable: boolean,
public readonly originalError?: Error
) {
super(message);
this.name = 'SupabaseServiceError';
}
}
export function wrapSupabaseError(error: unknown): SupabaseServiceError {
// Transform SDK errors to application errors
}
// src/supabase/health.ts
export async function checkSupabaseHealth(): Promise<HealthStatus> {
try {
const start = Date.now();
await supabaseClient.ping();
return {
status: 'healthy',
latencyMs: Date.now() - start,
};
} catch (error) {
return { status: 'unhealthy', error: error.message };
}
}
User Request
│
▼
┌─────────────┐
│ API │
│ Gateway │
└──────┬──────┘
│
▼
┌─────────────┐ ┌─────────────┐
│ Service │───▶│ Cache │
│ Layer │ │ (Redis) │
└──────┬──────┘ └─────────────┘
│
▼
┌─────────────┐
│ Supabase │
│ Client │
└──────┬──────┘
│
▼
┌─────────────┐
│ Supabase │
│ API │
└─────────────┘
// config/supabase.ts
export interface SupabaseConfig {
apiKey: string;
environment: 'development' | 'staging' | 'production';
timeout: number;
retries: number;
cache: {
enabled: boolean;
ttlSeconds: number;
};
}
export function loadSupabaseConfig(): SupabaseConfig {
const env = process.env.NODE_ENV || 'development';
return require(`./supabase.${env}.json`);
}
Set up the project layout following the reference structure above.
Create the singleton client with caching and monitoring.
Implement custom error classes for Supabase operations.
Add health check endpoint for Supabase connectivity.
| Issue | Cause | Solution |
|---|---|---|
| Circular dependencies | Wrong layering | Separate concerns by layer |
| Config not loading | Wrong paths | Verify config file locations |
| Type errors | Missing types | Add Supabase types |
| Test isolation | Shared state | Use dependency injection |
# Create reference structure
mkdir -p src/supabase/{handlers} src/services/supabase src/api/supabase
touch src/supabase/{client,config,types,errors}.ts
touch src/services/supabase/{index,sync,cache}.ts
For multi-environment setup, see supabase-multi-env-setup.