Supabase Local Dev Loop

What it does

When your agent uses it

• Initializing a Supabase project locally
• Starting the local stack
• Writing migrations
• Iterating on schema changes

Example prompts

• “supabase local dev”
• “supabase start”
• “supabase init”
• “/supabase-local-dev-loop”

Requirements

• Node.js
• Docker
• A credential in SUPABASE_ANON_KEY
• A credential in SUPABASE_SERVICE_ROLE_KEY
• Compatibility (from SKILL.md): Designed for Claude Code
• Pre-approved tools (allowed-tools): Read, Write, Edit, Bash(npx:*), Bash(supabase:*), Bash(docker:*), Bash(curl:*), Grep

Workflow steps

3 steps, taken from the step headings in SKILL.md.

1. 1Initialize Project and Start Local Stack
2. 2Create Migrations and Seed Data
3. 3Iterate with Diff-Based Migrations

What it can do on your machine

Read from SKILL.md and the folder at commit 23ea8d4. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read
  • Write
  • Edit
  • Bash(npx:*)
  • Bash(supabase:*)
  • Bash(docker:*)
  • Bash(curl:*)
  • Grep

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • npx
  • supabase
  • npm
  • curl

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • supabase.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • SUPABASE_ANON_KEY
  • SUPABASE_SERVICE_ROLE_KEY

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Designed for Claude Code

  From compatibility in the SKILL.md frontmatter.

Context cost

Supabase Local Dev Loop loads about 2.3k tokens when it runs, and up to ~2.9k if it reads all its reference files. Until then it costs about 94 tokens; SKILL.md has 428 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~94

When it runs · the whole SKILL.md, loaded when a task matches

~2.3k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~2.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteMentions a .env fileSKILL.md:77

  Create `.env.local` from these values (git-ignored):

• NoteMentions a .env fileSKILL.md:80

  # .env.local

• NoteMentions a .env fileSKILL.md:221

  - `.env.local` with local connection credentials

• NoteRuns commands with sudoSKILL.md:230

  rmissions | Add user to `docker` group: `sudo usermod -aG docker $USER` |

• NoteMentions a .env fileSKILL.md:297

  npx supabase functions serve --env-file .env.local

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jeremylongshore/tons-of-skills-marketplace at commit 23ea8d4, republished under its MIT licence (© jeremylongshore). 428 words, ~2,342 tokens.

name

supabase-local-dev-loop

description

Configure Supabase local development with the CLI, Docker, and migration workflow. Use when initializing a Supabase project locally, starting the local stack, writing migrations, seeding data, or iterating on schema changes. Trigger with phrases like "supabase local dev", "supabase start", "supabase init", "supabase db reset", "supabase local setup".

allowed-tools

Read, Write, Edit, Bash(npx:*), Bash(supabase:*), Bash(docker:*), Bash(curl:*), Grep

compatibility

Designed for Claude Code

version

1.54.0

license

MIT

author

Jeremy Longshore <jeremy@intentsolutions.io>

tags

saas, supabase, local-development, docker, postgres

# Initialize Supabase in your project root
npx supabase init

supabase/
├── config.toml          # Local stack configuration (ports, auth settings)
├── migrations/          # SQL migration files (version-controlled)
└── seed.sql             # Seed data (runs after migrations on db reset)

npx supabase start

API URL:          http://localhost:54321
GraphQL URL:      http://localhost:54321/graphql/v1
S3 Storage URL:   http://localhost:54321/storage/v1/s3
DB URL:           postgresql://postgres:postgres@localhost:54322/postgres
Studio URL:       http://localhost:54323
Inbucket URL:     http://localhost:54324
anon key:         eyJhbGciOiJI...
service_role key: eyJhbGciOiJI...

# .env.local
SUPABASE_URL=http://localhost:54321
SUPABASE_ANON_KEY=<anon-key-from-supabase-start>
SUPABASE_SERVICE_ROLE_KEY=<service-role-key-from-supabase-start>
DATABASE_URL=postgresql://postgres:postgres@localhost:54322/postgres

npx supabase status

npx supabase migration new create_profiles
# Creates: supabase/migrations/<timestamp>_create_profiles.sql

-- supabase/migrations/<timestamp>_create_profiles.sql
create table public.profiles (
  id uuid references auth.users(id) primary key,
  username text unique not null,
  avatar_url text,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Always enable RLS on public tables
alter table public.profiles enable row level security;

create policy "Public profiles are viewable by everyone"
  on public.profiles for select
  using (true);

create policy "Users can update own profile"
  on public.profiles for update
  using (auth.uid() = id);

-- Auto-create profile on signup via trigger
create or replace function public.handle_new_user()
returns trigger as $$
begin
  insert into public.profiles (id, username)
  values (new.id, new.raw_user_meta_data->>'username');
  return new;
end;
$$ language plpgsql security definer;

create trigger on_auth_user_created
  after insert on auth.users
  for each row execute procedure public.handle_new_user();

-- supabase/seed.sql (runs automatically after migrations on db reset)
insert into auth.users (id, email, raw_user_meta_data)
values
  ('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'alice@example.com',
   '{"username": "alice"}'),
  ('b2c3d4e5-f6a7-8901-bcde-f12345678901', 'bob@example.com',
   '{"username": "bob"}');

npx supabase db reset
# Drops the database, replays all migrations, runs seed.sql

# Generate a migration from the diff between migrations and current DB state
npx supabase db diff -f add_bio_to_profiles

# Review the generated file
cat supabase/migrations/*_add_bio_to_profiles.sql

-- Auto-generated by supabase db diff
alter table public.profiles add column bio text;

npx supabase db reset
# Success = all migrations + seed apply without errors

# Link to remote project first (one-time)
npx supabase link --project-ref <your-project-ref>

# Push migrations to remote
npx supabase db push

# Start of day
npx supabase start

# After schema changes in Studio
npx supabase db diff -f descriptive_name
npx supabase db reset          # Verify clean replay

# Before committing
npx supabase db reset          # Final verification
npm test                       # Run tests against local instance

# End of day
npx supabase stop

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.SUPABASE_URL!,       // http://localhost:54321 locally
  process.env.SUPABASE_ANON_KEY!   // Local anon key from supabase start
)

// Fetch profiles — works identically in local and production
const { data, error } = await supabase
  .from('profiles')
  .select('username, avatar_url')
  .limit(10)

import { createClient } from '@supabase/supabase-js'
import { describe, it, expect, beforeAll } from 'vitest'

const supabase = createClient(
  'http://localhost:54321',
  'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'  // Local anon key
)

describe('profiles', () => {
  beforeAll(async () => {
    // Seed data is already loaded via supabase db reset
  })

  it('fetches public profiles', async () => {
    const { data, error } = await supabase
      .from('profiles')
      .select('username')
      .limit(1)

    expect(error).toBeNull()
    expect(data).toHaveLength(1)
    expect(data![0].username).toBeDefined()
  })

  it('enforces RLS on update', async () => {
    // Anon users cannot update profiles (no auth.uid())
    const { error } = await supabase
      .from('profiles')
      .update({ username: 'hacker' })
      .eq('username', 'alice')

    expect(error).not.toBeNull()
  })
})

# Create and serve an Edge Function with hot reload
npx supabase functions new hello-world
npx supabase functions serve --env-file .env.local

# Test it
curl -X POST http://localhost:54321/functions/v1/hello-world \
  -H "Authorization: Bearer $SUPABASE_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "World"}'

© jeremylongshore, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 3 other files (references) in skills/.curated/supabase-local-dev-loop of jeremylongshore/tons-of-skills-marketplace.

• SKILL.md
• references/errors.md
• references/examples.md
• references/implementation.md

Open the folder on GitHubat commit 23ea8d4