First-Time Supabase Setup

This guide walks you through setting up a brand-new Supabase project for Cursorist. By the end, you will have a working database, authentication, storage, and a running local dev server.

What You Need Before Starting

• A Supabase account (free tier works)
• A GitHub account (for OAuth)
• Node.js 18+ installed
• The Cursorist repo cloned and npm install completed

Step 1 — Create a Supabase Project

1. Go to supabase.com/dashboard
2. Click New Project
3. Fill in:
   • Name: cursorist (or any name you prefer)
   • Database Password: generate a strong one and save it somewhere safe
   • Region: pick the closest to your users
4. Click Create new project
5. Wait ~2 minutes for provisioning to finish

Once ready, go to Settings → API and note these two values — you will need them shortly:

Step 2 — Create Storage Buckets

Go to Storage in the Supabase Dashboard and create three buckets:

For avatars, toggle Public bucket to ON when creating it. The other two stay private.

Step 3 — Run the Database Schema

Go to SQL Editor in the Dashboard and create a new query.

Open supabase/migrations/001_init.sql from the project. Copy the entire contents and paste it into the SQL Editor. Click Run.

This single file creates everything the platform needs:

• 15 tables (users, organizations, teams, plugins, versions, assets, channels, installs, favorites, api_keys, invitations, notifications, config)
• All indexes for fast queries
• Row Level Security policies on every table
• Trigger functions (auto-timestamps, auto-membership)
• Database functions (install count, version publishing, latest version lookup)
• Storage bucket policies (avatars, plugin-assets, exports)
• Realtime subscriptions (plugins, favorites, invitations)
• Default site config values (maintenance mode, debug mode, etc.)

If the query runs successfully with no errors, go to Table Editor to verify — you should see all tables listed.

Step 4 — Set Up GitHub OAuth

Cursorist uses GitHub for authentication. You need to create a GitHub OAuth App and connect it to Supabase.

Create a GitHub OAuth App

1. Go to github.com/settings/developers
2. Click OAuth Apps → New OAuth App
3. Fill in:
   • Application name: Cursorist (or Cursorist Dev for local)
   • Homepage URL: http://localhost:3000
   • Authorization callback URL: https://YOUR-PROJECT-REF.supabase.co/auth/v1/callback
4. Click Register application
5. Click Generate a new client secret
6. Copy both the Client ID and Client Secret

Enable GitHub in Supabase

1. Go to Authentication → Providers in the Supabase Dashboard
2. Find GitHub and expand it
3. Toggle it ON
4. Paste your Client ID and Client Secret
5. Click Save

Enable Signups

1. Go to Authentication → Settings
2. Make sure "Allow new users to sign up" is enabled
3. Save

Without this, you will get a "Signups are currently disabled" error when trying to log in.

Step 5 — Configure Environment Variables

Copy the example env file:

cp .env.example .env.local

Open .env.local and fill in your values:

NEXT_PUBLIC_SUPABASE_URL=https://YOUR-PROJECT-REF.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...your-anon-key
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIs...your-service-role-key
NEXT_PUBLIC_APP_URL=http://localhost:3000

The SUPABASE_SERVICE_ROLE_KEY is only needed for edge functions and admin operations. Never expose it in the browser.

Step 6 — Start the Dev Server

npm run dev

Open http://localhost:3000. You should see the Cursorist welcome page.

Test Authentication

1. Click Sign In
2. Click Sign in with GitHub
3. Authorize the app on GitHub
4. You should be redirected to the onboarding page (first time) or the explorer

If you see errors, check:

• Is your callback URL correct? It must be https://YOUR-PROJECT-REF.supabase.co/auth/v1/callback
• Is GitHub provider enabled in Supabase?
• Are signups enabled?

Step 7 — Seed Sample Data (Optional)

To populate the database with a sample organization, team, and plugin:

1. Go to SQL Editor in the Supabase Dashboard
2. Open supabase/seed_rules.sql from the project and paste it
3. Run the query

This creates a "Cursorist Community" organization with an "Open Source Plugins" team and a sample "TypeScript Starter Plugin" with version 1.0.0.

Note: The seed script requires a user to exist as the owner. You must sign in at least once before running it, then update the owner_user_id variable at the top of the seed file to match your user ID (find it in the users table).

Step 8 — Generate TypeScript Types (Optional)

If you want to regenerate the database types from your actual schema:

npx supabase gen types typescript --project-id YOUR-PROJECT-REF > lib/supabase/database.types.ts

The project already includes a manually maintained database.types.ts, so this step is only needed if you modify the schema.

Verify Everything Works

After completing all steps, check these:

Troubleshooting

"relation users does not exist" — The migrations did not run. Go to SQL Editor and run supabase/setup.sql again.

"Signups are currently disabled" — Enable signups in Authentication → Settings.

Callback URL mismatch — Make sure the GitHub OAuth App callback URL exactly matches https://YOUR-PROJECT-REF.supabase.co/auth/v1/callback.

"Invalid API key" — Double-check NEXT_PUBLIC_SUPABASE_ANON_KEY in .env.local. It should be the anon key, not the service_role key.

Storage policy errors — Make sure you created the three storage buckets before running the SQL setup. The policies reference bucket names that must already exist.

What's Next

• Database Schema — Full table and column reference
• Edge Functions — Deploy Supabase Edge Functions
• CLI Setup — Set up the Cursorist CLI
• Building Plugins — Create your first plugin