Development Setup - Wal33D/manic-miners-launcher GitHub Wiki

Development Setup

This guide will help you set up a development environment for the Manic Miners Launcher.

Prerequisites

Required Software

  1. Node.js 20.19.2 or later

    # Check your Node.js version
node --version
    • Download from nodejs.org
    • Use Node Version Manager (nvm) for version management

  2. pnpm Package Manager (v10.12.4)

    # Install pnpm globally
npm install -g [email protected]

# Verify installation
pnpm --version

  3. Git

    # Check Git installation
git --version

Platform-Specific Requirements

Windows Development

  • Visual Studio Build Tools or Visual Studio Community
  • Python 3.x (for native module compilation)
  • Windows SDK (usually included with Visual Studio)

macOS Development

  • Xcode Command Line Tools 
    xcode-select --install

Linux Development

  • Build Essential Tools

    # Ubuntu/Debian
sudo apt-get install build-essential

# CentOS/RHEL/Fedora
sudo yum groupinstall "Development Tools"

Project Setup

1. Clone the Repository

# Clone the repository
git clone https://github.com/Wal33D/manic-miners-launcher.git
cd manic-miners-launcher

2. Install Dependencies

# Install all dependencies (main project + GUI)
pnpm install

# This will install dependencies for:
# - Main Electron app (root)
# - React GUI (launcher-gui/)
# - Portal launch (manic-miner-portal-launch/)

3. Generate Assets

# Generate application assets
pnpm run generate:assets

This command creates optimized assets, icons, and other resources needed for the application.

4. Start Development

# Start the development environment
pnpm start

This command will:

  • Start the Electron main process
  • Launch the React development server
  • Enable hot reloading for both frontend and backend
  • Open the application in development mode

Development Scripts

Main Project Scripts

# Development
pnpm start                    # Start development mode with hot reload
pnpm run build               # Build the application
pnpm run make                # Create distributable packages
pnpm run package             # Package without creating distributables

# Code Quality
pnpm run lint                # Run ESLint on all code
pnpm run lint:fix            # Fix auto-fixable linting issues
pnpm run format              # Format code with Prettier

# Testing
pnpm test                    # Run all tests
pnpm run test:watch          # Run tests in watch mode
pnpm run test:verbose        # Run tests with detailed output

# Assets
pnpm run generate:assets     # Generate application assets

Frontend GUI Scripts (launcher-gui)

# Navigate to GUI directory
cd launcher-gui

# Development
pnpm dev                     # Start Vite dev server
pnpm build                   # Build for production
pnpm build:dev               # Build in development mode
pnpm preview                 # Preview production build

# Code Quality
pnpm lint                    # Run ESLint on frontend code

Project Structure

Understanding the project structure is crucial for development:

manic-miners-launcher/
├── src/                          # Electron main process
│   ├── main/                     # Main process code
│   │   ├── main.ts              # Application entry point
│   │   ├── createWindow.ts      # Window management
│   │   └── ipcHandlers/         # IPC communication handlers
│   ├── api/                     # External API communication
│   ├── functions/               # Core game management logic
│   ├── types/                   # TypeScript type definitions
│   └── utils/                   # Shared utilities
├── launcher-gui/                # React frontend
│   ├── src/
│   │   ├── components/          # React components
│   │   ├── pages/              # Application pages
│   │   ├── hooks/              # Custom React hooks
│   │   └── utils/              # Frontend utilities
│   └── public/                 # Static assets
├── config/                      # Webpack configuration
├── assets/                      # Game assets and images
└── wiki-pages/                  # Documentation (this wiki)

Development Workflow

1. Making Changes

Backend Changes (Electron Main Process)

  • Edit files in src/
  • Changes require application restart
  • Use pnpm start to restart automatically

Frontend Changes (React GUI)

  • Edit files in launcher-gui/src/
  • Hot reloading enabled - changes appear immediately
  • Check browser console for errors

2. Testing Your Changes

# Run the full test suite
pnpm test

# Run specific test files
pnpm test -- --grep "IPC handlers"

# Run tests in watch mode during development
pnpm run test:watch

3. Code Quality Checks

# Lint all code
pnpm run lint

# Fix linting issues automatically
pnpm run lint:fix

# Format all code
pnpm run format

# Type check
npx tsc --noEmit

4. Building for Testing

# Package the application for testing
pnpm run package

# Create distributable packages
pnpm run make

IDE Setup

Recommended IDEs

  • Visual Studio Code (recommended)
  • WebStorm
  • Atom

VS Code Extensions

  • ES7+ React/Redux/React-Native snippets
  • Prettier - Code formatter
  • ESLint
  • TypeScript Importer
  • Auto Rename Tag
  • Electron Color Theme (optional)

VS Code Settings

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.preferences.importModuleSpecifier": "relative"
}

Debugging

Debugging the Main Process

  1. VS Code Debug Configuration

    Create .vscode/launch.json:

    {
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Main Process",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
      "windows": {
        "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd"
      },
      "args": [".", "--remote-debugging-port=9223"],
      "outputCapture": "std"
    }
  ]
}

  2. Chrome DevTools

    • Open Chrome/Edge
    • Navigate to chrome://inspect
    • Click "Open dedicated DevTools for Node"

Debugging the Renderer Process

  1. Open DevTools in Development

    # Development mode includes DevTools access
pnpm start
# Press Ctrl+Shift+I or Cmd+Option+I

  2. React Developer Tools

    • Install React DevTools browser extension
    • Works in Electron development mode

Environment Variables

Create a .env file in the root directory:

# Development settings
NODE_ENV=development
DEBUG=true

# API endpoints
API_BASE_URL=https://manic-launcher.vercel.app

# Logging
LOG_LEVEL=debug
LOG_TO_FILE=true

Common Development Issues

"Module not found" errors

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
pnpm install

TypeScript compilation errors

# Check TypeScript configuration
npx tsc --noEmit --skipLibCheck

Electron won't start

# Rebuild native modules
pnpm run rebuild

Hot reload not working

# Restart the development server
pnpm start

Contributing Guidelines

Before submitting changes:

  1. Run Tests: pnpm test
  2. Lint Code: pnpm run lint
  3. Format Code: pnpm run format
  4. Build Successfully: pnpm run build
  5. Test Packaging: pnpm run package

See Contributing Guidelines for detailed information.

Ready to contribute? Check out our Project Architecture guide to understand the codebase better.