Developer Setup

Complete guide for developers setting up BlockForge for development or deployment.

Prerequisites

Before you begin, ensure you have:

• Node.js 18+ installed
• npm or yarn package manager
• Git for version control
• Supabase account (free tier is fine for development)
• Code editor (VS Code recommended)

Project Structure

blockforge/
├── src/                    # Source code
│   ├── components/        # React components
│   ├── pages/             # Page components
│   ├── services/          # API services
│   └── utils/             # Utilities
├── supabase/              # Supabase configuration
│   ├── functions/         # Edge Functions
│   └── *.sql              # Database migrations
├── docs-site/             # Documentation site (this)
├── cursor-blockforge-extension/  # Cursor extension
└── package.json

Initial Setup

1. Clone Repository

git clone https://github.com/simplyoddapps/blockforge.git
cd blockforge

2. Install Dependencies

npm install

3. Environment Configuration

Create .env.local in the project root:

VITE_SUPABASE_URL=your_supabase_project_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

See Configuration Guide for all environment variables.

4. Supabase Setup

1. Create Supabase Project

   • Go to supabase.com
   • Create a new project
   • Wait for project to initialize

2. Run Database Migrations

   • Go to SQL Editor in Supabase dashboard
   • Run scripts from supabase/ directory
   • Verify tables are created

3. Configure Storage

   • Create storage buckets
   • Set up RLS policies
   • Configure CORS if needed

See Supabase Setup Guide for detailed instructions.

5. Start Development Server

npm run dev

Visit http://localhost:5173

Development Workflow

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build
• npm run lint - Run ESLint
• npm test - Run tests
• npm run test:e2e - Run end-to-end tests

Code Organization

• Components - Reusable UI components in src/components/
• Pages - Route components in src/pages/
• Services - API and business logic in src/services/
• Hooks - Custom React hooks in src/hooks/
• Utils - Helper functions in src/utils/

Testing

Run tests during development:

# Unit tests
npm test

# E2E tests
npm run test:e2e

# Test with UI
npm run test:ui

Building for Production

Local Build

npm run build
npm run preview

Production Deployment

See Deployment Guide for production deployment instructions.

Troubleshooting

Common Issues

Port already in use:

# Kill process on port 5173
lsof -ti:5173 | xargs kill -9

Supabase connection errors:

• Verify environment variables
• Check Supabase project status
• Verify API keys

Build errors:

• Clear node_modules and reinstall
• Check Node.js version (18+)
• Review error messages for specific issues

Next Steps

• Supabase Setup
• AI Configuration
• Deployment Guide