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

busirocket-supabase-boundaries skill

safe

/skills/busirocket-supabase-boundaries

This skill helps enforce strict Supabase boundaries by centralizing access in services and avoiding direct calls from components.

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

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

Files (3)

SKILL.md

1.5 KB

---
name: busirocket-supabase-boundaries
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

## 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 that use Supabase. It enforces centralized Supabase access in small, typed service wrappers and prevents direct Supabase calls from UI, hooks, utilities, or route handlers. The goal is safer, easier-to-test, and more maintainable data access across TypeScript, React, Next.js, Rust, and Tauri codebases.

How this skill works

The skill inspects code for direct imports or calls to the Supabase client outside designated service modules and flags violations. It requires a single client module and dedicated services/supabase/* wrappers that expose focused, typed functions. Each rule includes clear examples of correct and incorrect patterns and recommends where to place the Supabase client and service wrappers.

When to use it

When adding or refactoring database access in a Supabase project
When enforcing architecture or security boundaries for server and client code
When creating typed service layers for unit testing and dependency injection
When auditing code to remove scattered Supabase imports and improve maintainability
When onboarding contributors to a codebase that must follow consistent access patterns

Best practices

Never import @supabase/supabase-js outside a single client module and service wrappers
Centralize all Supabase interactions in services/supabase/* and keep functions small and focused
Type inputs and outputs for every wrapper function to make tests and refactors safer
Avoid exposing raw Supabase client instances; return only domain-relevant data or helper functions
Use service wrappers to encapsulate auth, RBAC, and policy logic rather than sprinkling checks across components

Example use cases

Refactoring a Next.js app so components call services/users.getProfile() instead of using the Supabase client directly
Adding unit tests by mocking service wrapper functions rather than stubbing the Supabase client
Creating a single lib/supabase.ts client and multiple small service modules (e.g., services/supabase/posts.ts)
Auditing a mixed codebase to locate and remove direct Supabase imports from route handlers and hooks
Implementing server-side access controls inside service wrappers so UI code only receives sanitized results

FAQ

Why avoid importing the Supabase client everywhere?

Scattered imports make it hard to change authentication, add logging, mock data for tests, and enforce access policies. A single client and service layer centralize these concerns.

What belongs in a service wrapper versus a component?

Data fetching, permission checks, and transformations belong in service wrappers. Components should only call wrapper functions and render results.