Skip to Content
docsDeveloper Setup

Last Updated: 3/9/2026

Developer Setup Guide

This guide walks you through setting up the Agricultural Microworlds development environment.

Prerequisites

  • GitHub account
  • GitHub Codespaces access (or Docker Desktop for local development)
  • Basic knowledge of Git and command line

Quick Start (GitHub Codespaces)

1. Create a Codespace

  1. Navigate to the repository on GitHub
  2. Click the bright green Code button
  3. Go to the Codespaces tab
  4. Click the + button to create a new codespace on main

⏱️ Note: Initial build takes several minutes as it downloads a Linux image.

2. Handle Recovery Mode (Expected)

The codespace will likely start in recovery mode due to limited GitHub storage.

Fix:

# Clear temporary cache
sudo rm -rf /tmp/*
 
# Rebuild container
# Press CTRL + SHIFT + P
# Type: "Rebuild Container"
# Select "Rebuild" (NOT "Full Rebuild")

✅ Once the terminal no longer shows Running in Recovery Mode, you’re ready to continue.

3. Build and Run the Application

# Open terminal if not already open
# CTRL + SHIFT + J
 
# Navigate to client directory
cd agricultural-microworlds.client
 
# Install dependencies and build
npm run build
 
# Start development server
npm run dev

🌐 A new tab should open with the application. If not, click the link provided in the console.

Local Development (Docker Desktop)

Prerequisites

  • Docker Desktop installed and running
  • VS Code with Remote - Containers extension

Setup

  1. Clone the repository:

    git clone https://github.com/ksu-cs/development-project-agopsimulation.git
cd development-project-agopsimulation

  2. Open in VS Code:

    code .

  3. Reopen in container:

    • Press F1 or CTRL + SHIFT + P
    • Select: Remote-Containers: Reopen in Container

  4. Follow steps 3 from Quick Start above

Development Scripts

Frontend (Client)

cd agricultural-microworlds.client
 
# Development server
npm run dev
 
# Development server with SVG view
npm run dev:svg
 
# Build for production
npm run build
 
# Run tests
npm test
 
# Lint code
npm run lint
 
# Check code formatting
npm run prettier-check
 
# Fix code formatting
npm run prettier-fix
 
# Preview production build
npm run preview

Backend (Server)

cd Agricultural-Microworlds.Server
 
# Run server
dotnet run
 
# Build server
dotnet build
 
# Run tests
dotnet test

Project Structure

development-project-agopsimulation/
├── .devcontainer/              # Docker dev container config
├── .github/                    # GitHub Actions workflows
├── Agricultural-Microworlds.Server/  # ASP.NET backend
│   ├── Controllers/            # API controllers
│   ├── Program.cs              # Server entry point
│   └── *.csproj                # C# project file
├── agricultural-microworlds.client/  # React frontend
│   ├── src/
│   │   ├── Components/         # React components
│   │   ├── Simulation/         # Simulation engine
│   │   ├── SetUpCustomBlocks/  # Blockly block definitions
│   │   ├── States/             # Application states
│   │   └── App.jsx             # Root component
│   ├── tests/                  # Jest tests
│   ├── package.json            # NPM dependencies
│   └── vite.config.js          # Vite configuration
├── Diagrams/                   # Architecture diagrams
├── README.md                   # Project overview
└── SpecificationDocument.md    # Requirements & design

Common Issues

Issue: Codespace in Recovery Mode

Solution: Clear temp files and rebuild:

sudo rm -rf /tmp/*

Then rebuild container (CTRL + SHIFT + P → “Rebuild Container”)

Issue: Port Already in Use

Solution: Kill existing process:

# Find process using port 5173 (Vite default)
lsof -ti:5173 | xargs kill -9

Issue: Module Not Found

Solution: Reinstall dependencies:

cd agricultural-microworlds.client
rm -rf node_modules package-lock.json
npm install

Issue: Build Fails

Solution: Check Node version and clean build:

node --version  # Should be 18+
npm run prettier-fix
npm run lint
npm run build

Development Workflow

  1. Create a branch for your feature:

    git checkout -b feature/your-feature-name

  2. Make changes and test locally:

    npm test
npm run lint
npm run prettier-check

  3. Commit changes with clear messages:

    git add .
git commit -m "Add feature: description"

  4. Push and create pull request:

    git push origin feature/your-feature-name

  5. Wait for review and CI checks to pass

Testing

Running Tests

cd agricultural-microworlds.client
npm test

Writing Tests

  • Place test files in tests/ directory
  • Use .test.js or .spec.js suffix
  • Follow Jest conventions
  • Aim for 90%+ code coverage

Code Quality

Linting

npm run lint

Formatting

# Check formatting
npm run prettier-check
 
# Auto-fix formatting
npm run prettier-fix

Pre-commit Checklist

  • Tests pass (npm test)
  • Linting passes (npm run lint)
  • Code formatted (npm run prettier-check)
  • Build succeeds (npm run build)
  • Changes documented

Next Steps

Getting Help

  • Check the project Wiki
  • Review existing GitHub Issues
  • Ask in team communication channels
  • Consult the specification document
Architecture Overview