Running Supamode Locally

Start Supamode's development servers and Supabase, seed demo data, and configure your own database tables.

This guide covers starting Supamode locally, seeding demo data to explore the interface, and connecting your own Supabase project.

Quick Start

Start both servers in parallel (requires two terminal windows):

Terminal 1: Start Supabase

pnpm run supabase:web:start

Terminal 2: Start development servers

pnpm dev

Open http://localhost:5173 and sign in with:

  • Email: root@supamode.com
  • Password: testingpassword

Step-by-Step Setup

1. Start the Development Servers

Run the dev command to start both the frontend and backend:

pnpm dev

This starts:

ServiceURLTechnology
Frontendhttp://localhost:5173Vite + React Router 7
APIhttp://localhost:3000Hono.js

Vite proxies all /api/* requests to the Hono backend automatically, so the frontend can make API calls without CORS configuration.

2. Start Supabase

Ensure Docker is running, then start the Supabase containers:

pnpm run supabase:web:start

Supamode uses non-standard ports to avoid conflicts with your main application's Supabase instance:

ServiceURLPurpose
Supabase APIhttp://localhost:54331REST and Realtime APIs
PostgreSQLlocalhost:54332Direct database access
Supabase Studiohttp://localhost:54333Database admin UI
InBuckethttp://localhost:54334Email testing

3. Seed Demo Data

To explore Supamode with sample data, run the demo schema installation. Open Supabase Studio at http://localhost:54333, go to the SQL Editor, and run:

call supamode.install_demo_schema();

This creates:

  • Sample tables (posts, categories, tags, etc.)
  • Four user accounts with different permission levels
  • Pre-configured roles and permissions
  • Sample data to browse and edit

4. Sign In

After seeding, sign in at http://localhost:5173 with one of these accounts:

RoleEmailPasswordPermissions
Rootroot@supamode.comtestingpasswordFull access to everything
Adminadmin@supamode.comtestingpasswordSystem administration
Membermember@supamode.comtestingpasswordData read/write
Read-onlyreadonly@supamode.comtestingpasswordView only

Try signing in with different roles to see how the RBAC system restricts access. The read-only user, for example, cannot edit records or access settings.

Using Your Own Data

Once you've explored the demo, connect Supamode to your own Supabase project.

Option A: Local Development (Supabase Emulator)

If your project also uses the Supabase emulator locally, point Supamode to your project's ports.

In apps/app/.env:

VITE_SUPABASE_URL=http://localhost:54321

In apps/api/.env:

SUPABASE_URL=http://localhost:54321
SUPABASE_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres

Then add your migrations to apps/app/supabase/seeds/ so they run when Supamode's database resets.

Option B: Remote Supabase Project

To connect to a hosted Supabase project:

In apps/app/.env:

VITE_SUPABASE_URL=https://YOUR_PROJECT.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key

In apps/api/.env:

SUPABASE_URL=https://YOUR_PROJECT.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_DATABASE_URL=postgresql://postgres:PASSWORD@db.YOUR_PROJECT.supabase.co:5432/postgres

Sync Your Tables

After connecting to your database, sync your tables into Supamode's metadata system:

-- Sync all tables in a schema
select supamode.sync_managed_tables('public');
-- Or sync specific tables
select supamode.sync_managed_tables('public', 'users');
select supamode.sync_managed_tables('public', 'orders');
select supamode.sync_managed_tables('public', 'products');
-- Sync tables from custom schemas
select supamode.sync_managed_tables('billing', 'invoices');
select supamode.sync_managed_tables('billing', 'subscriptions');

Reset the Database

After adding your migrations and sync commands, reset to apply them:

pnpm run supabase:web:reset

This drops and recreates the database, runs all migrations, and executes seed files in order.

Development Commands

Common commands for local development:

CommandPurpose
pnpm devStart frontend and API servers
pnpm supabase:web:startStart Supabase containers
pnpm supabase:web:stopStop Supabase containers
pnpm supabase:web:resetReset database and run seeds
pnpm supabase:web:typegenGenerate TypeScript types from schema
pnpm lint:fixFix linting issues
pnpm typecheckRun TypeScript compiler checks
pnpm test:unitRun unit tests

Troubleshooting

"Invalid login credentials"

The demo accounts only exist after running the seed. Ensure you ran:

call supamode.install_demo_schema();

Port Already in Use

If port 5173 or 3000 is busy, check for running processes:

lsof -i :5173
lsof -i :3000

Kill the process or change Supamode's ports in the Vite and Hono configs.

Supabase Won't Start

Docker must be running. On macOS/Windows, ensure Docker Desktop is open. On Linux:

sudo systemctl start docker

If containers are stuck, try a fresh start:

pnpm supabase:web:stop
docker system prune -f
pnpm supabase:web:start

Changes Not Reflecting

Vite uses hot module replacement, but some changes (especially to API routes) require a restart:

# Stop servers with Ctrl+C, then restart
pnpm dev

For database schema changes, reset the database:

pnpm supabase:web:reset

Next Steps