Developer installation

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

Clone the repository

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

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

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:

Runs the Go map generator (cd map-generator && go run .)
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

Join the Discord

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

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

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

Fork the repository on GitHub
Create a feature branch: git checkout -b amazing-feature
Make your changes following the code style
Test thoroughly on multiple browsers if applicable
Commit with clear messages: git commit -m 'Add amazing feature'
Push to your fork: git push origin amazing-feature
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

Get Started

Game Guides

Development

​Prerequisites

​Installation

​Running the development server

​Full stack development

​Client only development

​Server only development

​Connecting to remote backends

​Staging environment

​Production environment

​Project structure

​Development tools

​Code formatting

​Linting

​Testing

​Performance testing

​Building for production

​Development build

​Production build

​Map generation

​View map generator documentation

​Generate new maps

​Format map generator code

​Git hooks

​Contributing to development

​Before you start

​Code quality requirements

​Pull request process

​Additional resources

Architecture documentation

API documentation

Authentication

Contribution guidelines

​Troubleshooting

​Getting help

Development Discord

GitHub issues

Translation Discord

Crowdin project

Build docs developers (and LLMs) love

Prerequisites

Installation

Running the development server

Full stack development

Client only development

Server only development

Connecting to remote backends

Staging environment

Production environment

Project structure

Development tools

Code formatting

Linting

Testing

Performance testing

Building for production

Development build

Production build

Map generation

View map generator documentation

Generate new maps

Format map generator code

Git hooks

Contributing to development

Before you start

Code quality requirements

Pull request process

Additional resources

Troubleshooting

Getting help