| name | supabase-known-pitfalls |
| description | Use when reviewing Supabase code, onboarding developers, auditing an existing
project, or debugging unexpected behavior — catches the twelve most common
Supabase mistakes: exposing the service_role key in client bundles, forgetting
to enable RLS, skipping connection pooling in serverless, .single() throwing on
empty results, missing .select() after insert/update, ignoring { data, error },
creating multiple client instances, and not using generated types.
Trigger with phrases like "supabase mistakes", "supabase anti-patterns",
"supabase pitfalls", "supabase code review", "supabase gotchas",
"supabase debugging", "what not to do supabase", "supabase common errors".
|
| allowed-tools | Read, Grep |
| version | 1.53.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","supabase","anti-patterns","code-review","debugging","security","pitfalls"] |
| compatibility | Designed for Claude Code, also compatible with Codex and OpenClaw |
Supabase Known Pitfalls
Overview
The twelve most common Supabase mistakes, ranked by severity: security (service_role exposure, missing RLS, permissive policies, no connection pooling), data integrity (ignoring { data, error }, missing .select() after mutations, .single() on optional results), and performance / maintainability (select('*'), N+1 queries, missing FK indexes, multiple client instances, no generated types). Each pitfall shows the broken code, why it fails, and the correct pattern using createClient from @supabase/supabase-js.
This SKILL.md carries the full pitfall table plus one representative fix per category. The verbatim broken-vs-correct code and detection queries for all twelve live in references/pitfalls.md — drill in there for depth.
Prerequisites
- Access to a Supabase project codebase for review
@supabase/supabase-js v2+ installed- Basic understanding of Row Level Security (RLS)
Instructions
Work the pitfalls top-down by severity. Fix every Critical finding before moving on — a single security miss can expose the whole database.
| # | Pitfall | Severity | Fix |
|---|
| 1 | service_role key in client bundle | Critical | anon key on client; service_role server-only, no NEXT_PUBLIC_ |
| 2 | Table without RLS | Critical | ALTER TABLE … ENABLE ROW LEVEL SECURITY right after CREATE TABLE |
| 3 | Overly permissive RLS policy | Critical | scope USING (…) to auth.uid(), never USING (true) for writes |
| 4 | No connection pooling in serverless | Critical | pooled string (Supavisor, port 6543), not the direct 5432 URL |
| 5 | Ignoring { data, error } | High | destructure both; check error before touching data |
