dotcom-arcade/CONTRIBUTING.md

Contributing to Dotcom Arcade

Thanks for your interest in contributing! We welcome bug fixes, features, documentation improvements, and questions.

What is Dotcom Arcade?

A self-hosted web application for browsing and playing games from Flashpoint Archive.

Tech Stack: Node.js 20+, Express, React 18, TypeScript, SQLite, TanStack Query, Tailwind CSS

Table of Contents

• Where to Start
• Getting Started
• Development Setup
• Running Tests
• Making Changes
• Submitting a Pull Request
• Code Style
• Reporting Bugs
• License

Where to Start

• Browse issues labeled good first issue or help wanted
• Check the project documentation for architecture and patterns

Getting Started

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/flashpoint-web.git
cd flashpoint-web

# Add upstream remote
git remote add upstream https://github.com/ORIGINAL_OWNER/flashpoint-web.git

# Keep your fork synced
git fetch upstream
git rebase upstream/master

Development Setup

Project Structure

backend/    # Express REST API + game content serving (:3100)
frontend/   # React + Vite application (:5173)
docs/       # Documentation

Option 1: Docker

# Configure environment
cp .env.example .env
# Edit .env - set FLASHPOINT_HOST_PATH and JWT_SECRET (required)

# Build and start
docker compose up -d --build

# View logs
docker compose logs -f

The app (UI and API) runs on http://localhost:80.

Option 2: Manual Setup (Recommended for Development)

Prerequisites:

• Node.js 20+
• Flashpoint Archive installed locally

# Install dependencies
npm run install:all

# Configure environment
cp backend/.env.example backend/.env
# Edit backend/.env - set FLASHPOINT_PATH to your Flashpoint installation

# Start development servers
npm run dev

Frontend runs on http://localhost:5173, backend on http://localhost:3100.

Running Tests

# Run all tests
npm test

# Backend tests with coverage
cd backend && npm test -- --coverage

# Frontend tests
cd frontend && npm test

Making Changes

Branch Naming

feat/add-playlist-export
fix/game-search-pagination
refactor/auth-service
docs/update-api-reference

Commit Messages

Follow Conventional Commits:

<type>(<scope>): <description>

feat(games): add advanced search filters
fix(auth): resolve token refresh race condition
docs: update deployment guide
refactor(api): simplify error handling

Types: feat, fix, docs, refactor, test, chore, perf

Workflow

1. Create a branch from master
2. Make your changes
3. Run npm run typecheck and npm test
4. Update documentation if needed
5. Submit a pull request

Submitting a Pull Request

Before Submitting

git fetch upstream
git rebase upstream/master
npm run typecheck
npm run format
npm test

PR Guidelines

• Keep PRs focused and reasonably sized
• Reference related issues (Fixes #123)
• Include a clear description of changes
• Update documentation for new features

Code Style

See CLAUDE.md for detailed coding standards. Key points:

• TypeScript: No any types, use unknown or proper interfaces
• Backend: Wrap async handlers with asyncHandler(), static routes before parameterized
• Frontend: Use @/ imports, all API calls through lib/api.ts, use theme tokens
• General: Validate inputs, handle errors properly, clean up resources

Run npm run format before committing.

Reporting Bugs

Before reporting, search existing issues to avoid duplicates.

Include:

• Steps to reproduce
• Expected vs actual behavior
• Environment details (OS, Node version, browser)
• Screenshots or logs if applicable

License

This project is licensed under GPL-3.0. By contributing, you agree that your contributions will be licensed under the same license.