Developer installation

Set up a local OpenFront development environment

Prerequisites

Before you begin, ensure you have the following installed:

• npm v10.9.2 or higher - Download npm
• Git - For cloning the repository
• Modern web browser - Chrome, Firefox, Edge, or Safari

OpenFront is a browser-based game with both client and server components. This guide covers setting up the full development environment.

Installation

1. Clone the repository

   git clone https://github.com/openfrontio/OpenFrontIO.git
   cd OpenFrontIO
   

   This downloads the complete OpenFront source code to your local machine.

2. Install dependencies

   npm run inst
   

   Important: Always use npm run inst instead of npm install or npm i.

   This command runs npm ci --ignore-scripts which:

   • Installs dependencies exactly as specified in package-lock.json
   • Skips running package scripts for security
   • Helps prevent supply chain attacks

   The installation includes dependencies for:

   • Client: Vite, PixiJS, Lit, TypeScript
   • Server: Express, WebSocket (ws), Winston logging
   • Testing: Vitest, ESLint, Prettier

Running the development server

Full stack development

Start both the client and server with live reloading:

npm run dev

This command:

• Starts the Vite development server for the client
• Launches the game server with development settings
• Opens the game in your default browser automatically
• Enables hot module reloading for rapid development

To prevent the browser from opening automatically, set the environment variable:

SKIP_BROWSER_OPEN=true npm run dev

Access the game:

• Client: http://localhost:5173 (Vite default)
• Server: http://localhost:3000 (Master server)
• Workers: Ports assigned by config.workerPortByIndex(workerId)

Client only development

Run just the frontend with hot reloading:

npm run start:client

Useful when:

• Working on UI components only
• Testing visual changes
• Developing client-side features

Server only development

Run just the backend with development settings:

npm run start:server-dev

Useful when:

• Testing game logic
• Debugging server issues
• Working on API endpoints

Connecting to remote backends

Staging environment

Connect your local client to staging API servers:

npm run dev:staging

Use this to:

• Test against staging data
• Verify user profiles and authentication
• Debug purchase flows

Production environment

Connect your local client to production API servers:

npm run dev:prod

Production connection notes:

• Use this for replaying production games
• Find the gitCommit value at https://api.openfront.io/game/[gameId]
• Checkout the same commit locally to replay correctly
• Unfinished games cannot be replayed on localhost

Project structure

Understanding the codebase organization:

OpenFrontIO/
├── src/
│   ├── client/          # Frontend game client (PixiJS, Lit)
│   ├── core/            # Shared game logic (MUST be tested)
│   └── server/          # Backend game server (Express, WebSocket)
├── resources/           # Static assets
│   ├── maps/            # 40+ map definitions
│   ├── images/          # Sprites and UI assets
│   ├── sounds/          # Audio files
│   ├── lang/            # Localization files
│   └── flags/           # Country flag icons
├── tests/               # Test suites
├── map-generator/       # Go-based map generation tool
└── docs/                # Architecture and API documentation

Key directories:

• /src/client - All frontend React/Lit components and game rendering
• /src/core - Game mechanics shared between client and server
• /src/server - Server logic, networking, and game state management
• /resources - Contains 40+ maps and all game assets

Development tools

Code formatting

Format all files using Prettier:

npm run format

The project uses:

• Prettier for code formatting
• Plugin for organizing imports
• Plugin for shell script formatting

Linting

Check for code issues:

npm run lint

Automatically fix issues:

npm run lint:fix

Configuration:

• ESLint 9 with TypeScript support
• Prettier integration for consistent formatting
• GitHub Actions formatter for CI output

Testing

Run the full test suite:

npm test

This runs:

• Unit tests with Vitest
• Server integration tests

With coverage reports:

npm run test:coverage

Testing requirement: All code changes in src/core MUST be tested. This is strictly enforced for contributions.

Performance testing

Run performance benchmarks:

npm run perf

Building for production

Development build

npm run build-dev

Creates a development build with:

• TypeScript type checking
• Source maps for debugging
• Development mode optimizations

Production build

npm run build-prod

Creates an optimized production build with:

• Type checking enforced (fails on errors)
• Minification and tree shaking
• Production optimizations

The build process uses Vite for fast compilation and Concurrent execution for parallel TypeScript checking.

Map generation

OpenFront uses a Go-based map generator:

View map generator documentation

npm run docs:map-generator

Generate new maps

npm run gen-maps

This:

1. Runs the Go map generator (cd map-generator && go run .)
2. Formats the output with Prettier

Format map generator code

npm run format:map-generator

Git hooks

The project uses Husky for Git hooks with lint-staged:

• Pre-commit: Automatically runs ESLint and Prettier on staged files
• Validation: Ensures code quality before commits

Setup is automatic after running npm run inst.

Contributing to development

Before you start

1. Join the Discord

   Request to join the development Discord server to coordinate with the team.

2. Understand the contribution path

   OpenFront uses a progressive contribution system:

   • New contributors: Limited to UI improvements and small bug fixes
   • Established contributors: Can work on complex features after several successful PRs
   • Core contributors: May modify critical game systems with extensive project experience
3. Open an issue first

   Before investing significant time:

   • Open a GitHub issue describing your planned contribution
   • Wait for maintainer feedback
   • Small improvements can proceed directly to PR

Code quality requirements

All contributions must meet these standards:

• Well-commented code following existing patterns
• No breaking changes to existing functionality
• Thorough testing before submission
• All src/core changes MUST include tests

Pull request process

1. Fork the repository on GitHub
2. Create a feature branch: git checkout -b amazing-feature
3. Make your changes following the code style
4. Test thoroughly on multiple browsers if applicable
5. Commit with clear messages: git commit -m 'Add amazing feature'
6. Push to your fork: git push origin amazing-feature
7. Open a pull request with:
   • Description of changes
   • Screenshots for UI changes
   • Testing methodology
   • Rationale for the change

The project maintainer (evan) has final authority on all code changes. Not all contributions will be accepted - the focus is on long-term project health.

Additional resources

Architecture documentation

Review docs/Architecture.md for system design details

API documentation

See docs/API.md for endpoint specifications

Authentication

Learn about auth flows in docs/Auth.md

Contribution guidelines

Read CONTRIBUTING.md for detailed contribution rules

Troubleshooting

Port conflicts

If you see port already in use errors:

• Default client port: 5173 (Vite)
• Default server port: 3000 (Master)
• Worker ports: Dynamically assigned

Kill processes using these ports or configure different ones in the environment.

Module not found errors

Ensure you used npm run inst and not npm install:

rm -rf node_modules package-lock.json
npm run inst

TypeScript errors

The project requires TypeScript 5.7.2+. Type errors will block production builds:

npx tsc --noEmit

Browser not opening

Set the environment variable:

export SKIP_BROWSER_OPEN=true
npm run dev

Getting help

Development Discord

Ask questions and get help from the dev community

GitHub issues

Report bugs or request features

Translation Discord

Join the translation community

Crowdin project

Help translate the game into your language