Supabase

Postgres database, authentication, storage and realtime behind one client.

adds it to an existing project · no account needed
Currentas published in v1.5.1

The rule

This is the whole text, exactly as your agent receives it. Nothing is held back for the paid tier.

Access

  • One client instance, in src/services/supabase/client.ts. Never call createClient anywhere else.
  • Components never import @supabase/supabase-js. They call a service in src/services/, which owns the query.
  • Every query is typed from the generated database.types.ts. Regenerate it after a schema change; do not hand-edit it.

Every response has an error

ts
const { data, error } = await supabase.from('profiles').select('id, name');
if (error) throw new Error(`Failed to load profiles: ${error.message}`);

The client does not throw. An unchecked error silently reads as an empty result, which is the single most common Supabase bug.

Queries

  • Select the columns you need. select('*') fetches everything and breaks the day someone adds a large column.
  • Paginate with .range() for anything unbounded.
  • Filter in the query, not in JavaScript after fetching.
  • Any column used in a filter or join needs an index.

Security

  • RLS enabled on every table. No exceptions. The anon key is public — it ships inside the app — so RLS is the only thing protecting the data.
  • The service_role key never appears in client code, in an {{envPrefix}}* variable, or in this repository. It bypasses every policy.
  • If a query needs privileges the user does not have, the answer is an edge function or an RLS policy — never a more powerful key in the client.

Schema

  • Schema changes are migration files in supabase/migrations/, committed to git. Never change the schema through the dashboard: environments drift and the divergence only shows up during a release.
  • Migrations must be compatible with the currently deployed app version, so a rollback does not corrupt data.

Auth

  • Initialise auth state once at startup and subscribe to onAuthStateChange.
  • Never read a user id from client state for an authorisation decision — the policy uses auth.uid(), which the client cannot forge.

6 formats, one per tool

Each tab is the file that tool actually reads, at the path it actually looks in. Knowing where each one looks is most of the work of supporting it.

.cursor/rules/supabase.mdchand-written
---
description: Supabase conventions
globs: ["src/services/**/*.ts", "supabase/**/*.sql"]
alwaysApply: false
---

# Supabase

## Access

- One client instance, in `src/services/supabase/client.ts`. Never call
  `createClient` anywhere else.
- Components never import `@supabase/supabase-js`. They call a service in
  `src/services/`, which owns the query.
- Every query is typed from the generated `database.types.ts`. Regenerate it
  after a schema change; do not hand-edit it.

## Every response has an error

```ts
const { data, error } = await supabase.from('profiles').select('id, name');
if (error) throw new Error(`Failed to load profiles: ${error.message}`);
```

The client does not throw. An unchecked `error` silently reads as an empty
result, which is the single most common Supabase bug.

## Queries

- Select the columns you need. `select('*')` fetches everything and breaks the
  day someone adds a large column.
- Paginate with `.range()` for anything unbounded.
- Filter in the query, not in JavaScript after fetching.
- Any column used in a filter or join needs an index.

## Security

- **RLS enabled on every table.** No exceptions. The anon key is public — it
  ships inside the app — so RLS is the only thing protecting the data.
- The `service_role` key never appears in client code, in an `{{envPrefix}}*`
  variable, or in this repository. It bypasses every policy.
- If a query needs privileges the user does not have, the answer is an edge
  function or an RLS policy — never a more powerful key in the client.

## Schema

- Schema changes are migration files in `supabase/migrations/`, committed to
  git. Never change the schema through the dashboard: environments drift and
  the divergence only shows up during a release.
- Migrations must be compatible with the currently deployed app version, so a
  rollback does not corrupt data.

## Auth

- Initialise auth state once at startup and subscribe to `onAuthStateChange`.
- Never read a user id from client state for an authorisation decision — the
  policy uses `auth.uid()`, which the client cannot forge.

Hand-written by the module author, frontmatter and all. It is the source the four derived formats are rendered from, so a correction lands here first.

What else this module writes

The rule is one file of several. Selecting Supabase contributes all of this too — merged with every other module you pick, with conflicts resolved rather than duplicated.

Environment
{{envPrefix}}SUPABASE_URLrequiredProject URL from Project Settings → API.
{{envPrefix}}SUPABASE_ANON_KEYrequiredPublic anon key. Safe in the client only because RLS is enabled.
SUPABASE_SERVICE_ROLE_KEYoptionalServer-side only. Bypasses all RLS. Never expose to the client.
SUPABASE_PROJECT_REFoptionalProject reference used by the CLI for migrations.
Dependencies
Depends on the rest of the stack — this module installs different packages depending on what else you select, so there is no single list to show.
Folders
src/services/supabase/supabase/migrations/supabase/functions/
Checklists
checklists/supabase-security.md

Advisory history

Every time this rule turned out to be wrong, and what we did about it.

No corrections yet

This rule has been accurate since it was published. That is a fact about the rule, not a promise about the future — which is the whole reason this section exists.

Pro tells you the day a correction lands that affects a repo you actually have.

See what Pro adds →

Rules people add alongside this one

conflicts withFirebase
Put this rule in a real project

The wizard picks the rest of the stack with you, writes all 6 formats, and leaves a manifest so check can tell you when any of it drifts.