Development Setup Guide

This guide provides comprehensive instructions for setting up a development environment for PadawanForge, including all necessary tools, dependencies, and configuration.

Prerequisites

Required Software

Node.js

# Install Node.js 18+ (required for Astro and Cloudflare Workers)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version

Git

# Install Git
sudo apt-get install git

# Configure Git
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Cloudflare Account

  1. Create a Cloudflare account
  2. Install Wrangler CLI: npm install -g wrangler
  3. Authenticate: wrangler login

VS Code Extensions

{
  "recommendations": [
    "astro-build.astro-vscode",
    "bradlc.vscode-tailwindcss",
    "esbenp.prettier-vscode",
    "ms-vscode.vscode-typescript-next",
    "ms-vscode.vscode-json"
  ]
}

Database Browser

  • D1 Browser: Built into Wrangler CLI
  • SQLite Browser: For local database inspection

Repository Setup

Clone Repository

# Clone the repository
git clone https://github.com/your-org/PadawanForge.git
cd PadawanForge

# Install dependencies
npm install

Environment Configuration

# Create development environment file
cp .env.example .dev.vars

# Edit environment variables
nano .dev.vars

Required Environment Variables

# Core application settings
API_TOKEN=your_secure_token_here
APP_NAME=PadawanForge
SESSION_DURATION=420
DEFAULT_DIFFICULTY=basic

# Database configuration (will be set by wrangler)
# DATABASE_URL is automatically configured

# OAuth providers (optional for basic development)
OAUTH_GOOGLE_CLIENT_ID=your_google_client_id
OAUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret

Database Setup

Create D1 Database

# Create database
npm run wrangler d1 create padawan-db

# Note the database_id from output
# Update wrangler.jsonc with the database_id

Update Wrangler Configuration

// wrangler.jsonc
{
  "name": "padawanforge-dev",
  "compatibility_date": "2024-01-01",
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "padawan-db",
      "database_id": "your-database-id-here"
    }
  ],
  "kv_namespaces": [
    {
      "binding": "SESSION",
      "id": "your-sessions-kv-namespace-id"
    }
  ],
  "r2_buckets": [
    {
      "binding": "FILES",
      "bucket_name": "padawanforge-dev-assets"
    }
  ],
  "ai": {
    "binding": "AI"
  }
}

Run Database Migrations

# Run all migrations
npm run db:migrate

# Verify database setup
npm run wrangler d1 execute padawan-db --command "SELECT name FROM sqlite_master WHERE type='table';"

Storage Setup

Create KV Namespaces

# Create sessions KV namespace
npm run wrangler kv:namespace create "PADAWAN_SESSIONS"

# Update wrangler.jsonc with the namespace IDs

Create R2 Bucket

# Create R2 bucket
npm run wrangler r2 bucket create padawanforge-dev-assets

# Configure CORS for R2
npm run wrangler r2 bucket cors put padawanforge-dev-assets --file cors.json

CORS Configuration

// cors.json
[
  {
    "AllowedOrigins": ["http://localhost:4321", "https://your-domain.com"],
    "AllowedMethods": ["GET", "POST", "PUT", "DELETE"],
    "AllowedHeaders": ["*"],
    "MaxAgeSeconds": 3000
  }
]

OAuth Provider Setup

Google OAuth

  1. Visit Google Cloud Console
  2. Create new project or select existing
  3. Enable Google+ API
  4. Create OAuth 2.0 credentials
  5. Add redirect URI: http://localhost:4321/api/auth/callback/google
  6. Copy Client ID and Secret to .dev.vars

Discord OAuth

  1. Visit Discord Developer Portal
  2. Create new application
  3. Go to OAuth2 section
  4. Add redirect URI: http://localhost:4321/api/auth/callback/discord
  5. Copy Client ID and Secret to .dev.vars

Development Workflow

Start Development Server

# Start development server
npm run dev

# Server will be available at http://localhost:4321

Development Commands

# Run tests
npm run test:all

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e

# Build for production
npm run build

# Preview production build
npm run preview

# Deploy to Cloudflare
npm run deploy

Database Management

# Create new migration
npm run db:migrate:create migration_name

# Run migrations
npm run db:migrate

# Rollback migration
npm run db:rollback

# Reset database
npm run db:reset

Code Quality Tools

Linting and Formatting

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Type checking
npm run type-check

Testing

# Run all tests
npm run test:all

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm test src/components/MyComponent.test.ts

Debugging

Development Tools

# Enable debug logging
DEBUG_MODE=true npm run dev

# Run with specific log level
LOG_LEVEL=debug npm run dev

Database Debugging

# Query database directly
npm run wrangler d1 execute padawan-db --command "SELECT * FROM players LIMIT 5;"

# View database schema
npm run wrangler d1 execute padawan-db --command ".schema"

API Debugging

# Test API endpoints
curl -X GET http://localhost:4321/api/health

# Test with authentication
curl -X GET http://localhost:4321/api/players \
  -H "Cookie: session=your-session-token"

Troubleshooting

Common Issues

Port Already in Use

# Find process using port 4321
lsof -i :4321

# Kill process
kill -9 <PID>

# Or use different port
PORT=4322 npm run dev

Database Connection Issues

# Check database status
npm run wrangler d1 execute padawan-db --command "SELECT 1;"

# Verify wrangler configuration
cat wrangler.jsonc

# Recreate database if needed
npm run wrangler d1 delete padawan-db
npm run wrangler d1 create padawan-db

OAuth Issues

# Check OAuth configuration
echo $OAUTH_GOOGLE_CLIENT_ID
echo $OAUTH_GOOGLE_CLIENT_SECRET

# Verify redirect URIs match
# Should be: http://localhost:4321/api/auth/callback/google

Build Issues

# Clear cache
rm -rf node_modules/.cache
rm -rf dist

# Reinstall dependencies
npm install

# Rebuild
npm run build

Performance Optimization

Development Performance

# Enable fast refresh
FAST_REFRESH=true npm run dev

# Use development optimizations
NODE_ENV=development npm run dev

Build Optimization

# Analyze bundle size
npm run build:analyze

# Optimize images
npm run optimize:images

# Minify assets
npm run build:minify

Security Considerations

Development Security

# Use strong API tokens
API_TOKEN=$(openssl rand -hex 32)

# Secure session configuration
SESSION_SECRET=$(openssl rand -hex 32)

# Enable HTTPS in development
HTTPS=true npm run dev

Environment Security

# Never commit secrets
echo ".dev.vars" >> .gitignore
echo "*.key" >> .gitignore
echo "secrets/" >> .gitignore

Next Steps

After Setup

  1. Verify Installation: Run npm run test:all to ensure everything works
  2. Explore Codebase: Review the architecture documentation
  3. Run Demo: Visit http://localhost:4321/demo to test the application
  4. Join Development: Check the contributing guidelines

Learning Resources

This setup guide provides everything needed to start developing with PadawanForge. For additional help, check the troubleshooting section or reach out to the development team.

← Release Structure Shared Utilities →
PadawanForge v1.4.1