supabase-reference-architecture skill

Overview

This skill implements a Supabase reference architecture with a best-practice project layout, client wrapper, error handling, and health checks. It helps teams establish consistent patterns for new Supabase integrations and reviews. Use it to bootstrap structured, maintainable Supabase applications quickly.

How this skill works

The skill provides a recommended directory structure and guides on creating a singleton Supabase client that includes caching and monitoring. It defines custom error classes and an error boundary pattern for predictable error handling. It also shows how to expose a health-check endpoint that verifies Supabase connectivity and basic operations.

When to use it

• Designing a new Supabase-backed application or microservice
• Onboarding teams to a consistent Supabase project layout
• Reviewing or refactoring an existing Supabase integration
• Establishing architecture standards and best practices for data access
• Implementing observability and resilience around Supabase calls

Best practices

• Organize code into clear layers: api, services, clients, models, and tests
• Use a singleton client wrapper to centralize caching, retries, and metrics
• Define explicit custom error classes for common Supabase failures
• Keep health checks lightweight: simple connectivity and sample query
• Write tests around client behavior, caching, and error handling

Example use cases

• Initialize a new TypeScript project with the recommended folder layout before adding features
• Replace ad-hoc Supabase calls with a centralized client to add caching and monitoring
• Add a health-check endpoint to Kubernetes liveness/readiness probes
• Standardize error responses across services by using shared error classes
• Create onboarding guides and templates for developers joining the project

FAQ