home / skills / busirocket / agents-skills / busirocket-supabase

busirocket-supabase skill

safe

This skill enforces centralized Supabase access and boundary rules to prevent direct calls from components, hooks, or utils.

npx playbooks add skill busirocket/agents-skills --skill busirocket-supabase

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.6 KB

---
name: busirocket-supabase
description:
  Supabase access patterns and service boundaries. Use only when working with
  Supabase projects. Centralize Supabase access in services/ and never call
  Supabase directly from components/hooks/utils/route handlers.
disable-model-invocation: true
metadata:
  author: cristiandeluxe
  version: "1.0.0"
---

# Supabase Boundaries

Service boundary patterns for Supabase projects.

## When to Use

Use this skill only when:

- Working in a project that uses Supabase
- Creating or refactoring Supabase access code
- Enforcing service boundaries for database access

## Non-Negotiables (MUST)

- **Never call Supabase directly** from components, hooks, utils, or route
  handlers.
- **Centralize access** in dedicated Supabase service wrappers (e.g.
  `services/supabase/*`).
- Keep wrappers small, focused, and typed.
- Never import `@supabase/supabase-js` outside a single Supabase client module
  (e.g. `lib/supabase.ts`) or your Supabase service wrappers.

## Rules

### Supabase Access

- `supabase-access-rule` - Isolate Supabase access in service wrappers
- `supabase-services-usage` - Route handlers, hooks, utils, and components must
  NOT call Supabase directly

## Related Skills

- `busirocket-core-conventions` - Service boundaries and structure

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/supabase-access-rule.md
rules/supabase-services-usage.md
```

Each rule file contains:

- Brief explanation of why it matters
- Code examples (correct and incorrect patterns)
- Additional context and best practices

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

FAQ

Why forbid direct Supabase calls from components and hooks?

Direct calls scatter database logic across the codebase, make testing harder, and couple UI to backend internals. Centralizing access improves maintainability and observability.

Where should the Supabase client live?

Keep a single client module (e.g., lib/supabase.ts) and only import it inside your service wrappers under services/supabase/.

How do I migrate existing direct calls?

Extract the query into a new, typed function in a service wrapper, update callers to use that function, and remove direct client imports from higher layers.