Skip to main content

Local Development Setup

This guide walks through setting up Village Data for local development.

Prerequisites​

  • Node.js 18+
  • pnpm
  • Docker (for local Supabase)
  • Supabase CLI

Install Supabase CLI​

brew install supabase/tap/supabase
supabase --version

Clone and Install​

git clone https://github.com/villagedata/platform.git
cd platform/prototype
pnpm install

Start Local Supabase​

supabase start

This starts a local Supabase instance with:

  • PostgreSQL database on port 54322
  • Auth server on port 54321
  • Storage server
  • Studio UI at http://localhost:54323

Environment Variables​

Create .env.local files in the ui/ directory:

# ui/.env.local
NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=<from supabase start output>
NEXT_PUBLIC_APP_URL=http://localhost:3000
SUPABASE_SERVICE_ROLE_KEY=<from supabase start output>

See Environment Variables for the full list.

Run Migrations​

Migrations run automatically with supabase start, but you can manually run:

supabase db reset

Start Development Server​

cd ui
pnpm dev

The app is now available at http://localhost:3000.

Common Issues​

PostgreSQL Version Mismatch​

After upgrading Supabase CLI:

supabase stop --no-backup
supabase start

Migration Notices​

Notices like trigger does not exist, skipping are harmless - the migration uses DROP IF EXISTS before creating objects.

Project Structure​

prototype/
├── ui/                    # Next.js frontend
│   ├── src/
│   │   ├── app/          # App Router pages
│   │   ├── components/   # React components
│   │   ├── lib/          # Utilities
│   │   └── types/        # TypeScript types
│   └── public/
├── server/               # Backend services
│   └── packages/
│       ├── api/          # API server
│       ├── mcp/          # MCP server
│       └── shared/       # Shared code
├── supabase/
│   ├── migrations/       # SQL migrations
│   └── config.toml       # Local config
└── docs-site/            # This documentation