Local Development

A complete guide for setting up and running the application locally with Docker-based Supabase.

Prerequisites Installation (New Computer)

1. Install Git

Windows:

1. Download from https://git-scm.com/download/win
2. Run installer, use default options
3. Restart terminal

Mac:

xcode-select --install

Verify:

git --version

2. Install Node.js (v20.10.0+)

Recommended: Use nvm (Node Version Manager)

Windows:

1. Download nvm-windows from https://github.com/coreybutler/nvm-windows/releases
2. Run nvm-setup.exe
3. Restart terminal
4. Install Node:

   nvm install 20
   nvm use 20
   

Mac/Linux:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Restart terminal, then:
nvm install 20
nvm use 20

Verify:

node --version   # Should be >= 20.10.0

3. Install pnpm (v10.19.0+)

After Node.js is installed:

corepack enable
corepack prepare pnpm@10.19.0 --activate

Or install directly:

npm install -g pnpm@10.19.0

Verify:

pnpm --version   # Should be >= 10.19.0

4. Install Docker Desktop

Windows:

1. Download from https://www.docker.com/products/docker-desktop/
2. Run installer
3. Restart computer
4. Launch Docker Desktop
5. Wait for it to fully start (whale icon in system tray stops animating)

Mac:

1. Download from https://www.docker.com/products/docker-desktop/
2. Drag to Applications
3. Launch Docker Desktop
4. Wait for it to fully start

Verify:

docker --version
docker ps        # Should work without errors

Note (Windows): You may need to enable WSL 2. Docker Desktop will prompt you if needed.

5. Install VS Code

VS Code works on Windows, Mac, and Linux.

1. Download from https://code.visualstudio.com/
2. Run installer
3. Install recommended extensions when prompted after opening the project

6. Install Claude Code (AI Assistant)

Claude Code is an AI-powered CLI tool that helps with development.

Install via npm:

npm install -g @anthropic-ai/claude-code

Verify:

claude --version

First run setup:

claude

This will prompt you to authenticate with your Anthropic account.

Usage:

# Start Claude in your project directory
cd eminentid-monorepo
claude

# Or open directly in VS Code terminal

Note: Requires an Anthropic account. Sign up at https://console.anthropic.com/

Verify All Prerequisites

Run these commands to confirm everything is installed:

git --version     # Should return version info
node --version    # Should be >= 20.10.0
pnpm --version    # Should be >= 10.19.0
docker --version  # Should return version info
docker ps         # Should work without errors (Docker running)
claude --version  # Should return version info (optional but recommended)

All commands should succeed before proceeding.

Step 1: Clone the Repository

git clone https://github.com/SioInc/eminentid-monorepo.git
cd eminentid-monorepo

Step 2: Install Dependencies

pnpm install

This installs all dependencies across the monorepo.

Step 3: Set Up Environment Variables

Generate environment files using the built-in generator:

pnpm env:generate

Or manually copy the example file:

cp apps/web/.env.example apps/web/.env.local

Required Local Variables

Update apps/web/.env.local with these values for local development:

# Supabase Local (Docker)
NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_PUBLIC_KEY=<your-local-anon-key>
SUPABASE_SECRET_KEY=<your-local-service-role-key>

# Application
NEXT_PUBLIC_SITE_URL=http://localhost:3000

Note: The local Supabase keys are printed when you start Supabase (Step 4).

Step 4: Start Supabase (Docker)

Make sure Docker Desktop is running, then:

pnpm supabase:web:start

This will:

1. Pull required Docker images (first run only)
2. Start PostgreSQL database
3. Start Supabase services (Auth, Storage, etc.)
4. Apply all migrations from apps/web/supabase/migrations/
5. Run seed data if apps/web/supabase/seed.sql exists

First Run Output

On first run, you'll see output like:

Started supabase local development setup.

         API URL: http://localhost:54321
     GraphQL URL: http://localhost:54321/graphql/v1
          DB URL: postgresql://postgres:postgres@localhost:54322/postgres
      Studio URL: http://localhost:54323
    Inbucket URL: http://localhost:54324
        anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Copy the anon key and service_role key into your .env.local file:

• anon key → NEXT_PUBLIC_SUPABASE_PUBLIC_KEY
• service_role key → SUPABASE_SECRET_KEY

Step 5: Start the Development Server

pnpm dev

This starts all apps in the monorepo in development mode.

Step 6: Access the Application

Step 7: Create Your First User

1. Navigate to http://localhost:3000/auth/sign-up
2. Enter an email and password
3. Check http://localhost:54324 (Inbucket) for the confirmation email
4. Click the confirmation link
5. You're logged in!

Common Commands Reference

Development

Supabase

Database Migrations

Other

Troubleshooting

Docker Not Running

Error: Cannot connect to the Docker daemon

Fix: Start Docker Desktop and wait for it to fully initialize.

Port Already in Use

Error: Port 3000 is already in use

Fix (Windows):

netstat -ano | findstr :3000
taskkill /PID <PID> /F

Fix (Mac/Linux):

lsof -i :3000
kill -9 <PID>

Supabase Won't Start

# Stop everything
pnpm supabase:web:stop

# Clean Docker (removes unused containers/images)
docker system prune -a

# Start fresh
pnpm supabase:web:start

Database Connection Error

# Ensure Docker is running
docker ps

# Reset Supabase completely
pnpm supabase:web:reset

Migrations Out of Sync

If your local DB is out of sync with migrations:

# This wipes the DB and reapplies all migrations
pnpm supabase:web:reset

Missing Environment Variables

Error: Please provide the variable NEXT_PUBLIC_SUPABASE_URL

Fix: Run pnpm env:generate or manually create apps/web/.env.local with required variables.

Types Out of Date

After changing the database schema:

pnpm supabase:web:typegen

Workflow: Making Database Changes

1. Create a migration:

   pnpm --filter web supabase migrations new my_change
   

2. Edit the SQL file in apps/web/supabase/migrations/

3. Apply the migration:

   pnpm --filter web supabase migrations up
   

4. Regenerate types:

   pnpm supabase:web:typegen
   

5. Test locally, then push to development branch

Environment Overview

See the Preview Environments guide for staging/production workflow.

Quick Start Checklist

• Node.js 20.10.0+ installed
• pnpm 10.19.0+ installed
• Docker Desktop installed and running
• Repository cloned
• pnpm install completed
• .env.local configured with local Supabase keys
• pnpm supabase:web:start successful
• pnpm dev running
• http://localhost:3000 loads
• http://localhost:54323 (Supabase Studio) accessible