busirocket-supabase_skill

Overview

This skill defines service boundary patterns for projects using Supabase. It enforces centralizing Supabase access into small, typed service wrappers and prevents direct Supabase calls from UI, hooks, utils, or route handlers. Use it to keep database access predictable, auditable, and easy to test.

How this skill works

The skill inspects code for imports and usage of the Supabase client and flags violations where components, hooks, utils, or route handlers call Supabase directly. It enforces a single client module and encourages dedicated service files (e.g., services/supabase/*) that encapsulate queries and mutations. Each rule includes examples of correct and incorrect patterns and guidance for migrating existing calls into services.

When to use it

• When adding or refactoring Supabase-related features in a project
• During code reviews to ensure database access follows team conventions
• When establishing service boundaries for maintainability and testing
• Before deploying changes that touch authentication or database queries
• When onboarding new contributors to ensure consistent access patterns

Best practices

• Create one canonical Supabase client module and import it only in service wrappers
• Keep service wrappers small, focused, and fully typed for clear contracts
• Expose high-level functions from services instead of raw query objects
• Avoid exporting the raw Supabase client from services to prevent accidental use
• Write unit tests for service wrappers and mock the client in higher layers

Example use cases

• Refactoring route handlers to call services/supabase/authService.login instead of using supabase client directly
• Moving repeated queries into a usersService with typed input/output for reuse
• Auditing the codebase to find and replace stray @supabase/supabase-js imports outside the client module
• Creating a test harness that stubs service functions rather than stubbing Supabase in UI tests
• Onboarding new engineers with clear examples of correct and incorrect access patterns