Skip to main content
This guide will help you set up a local development environment for contributing to OpenFront.

​
Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Recent version (LTS recommended)

npm

Version 10.9.2 or higher

Git

For version control

Modern Browser

Chrome, Firefox, Edge, or Safari

​
Installation

1

Fork the Repository

Go to github.com/openfrontio/OpenFrontIO and click the “Fork” button in the top right.
2

Clone Your Fork

Clone your forked repository locally:
git clone https://github.com/YOUR_USERNAME/OpenFrontIO.git
cd OpenFrontIO
3

Install Dependencies

Use npm run inst instead of npm install. This runs npm ci --ignore-scripts to ensure a consistent and secure environment.
npm run inst
This command:
  • Installs dependencies exactly according to package-lock.json
  • Skips post-install scripts for security
  • Prevents supply chain attacks

​
Running the Game

​
Full Development Mode

Run both client and server with live reloading: 
npm run dev
This command:
  • Starts the Vite dev server on port 9000
  • Launches the game server with development settings
  • Opens the game in your default browser
  • Enables hot module replacement (HMR)
Set SKIP_BROWSER_OPEN=true in your environment to prevent automatic browser opening.

​
Client Only

Run just the frontend with Vite: 
npm run start:client
The client will be available at http://localhost:9000.

​
Server Only

Run just the game server: 
npm run start:server-dev
The start:server-dev script sets GAME_ENV=dev for development-specific behavior.

​
Connecting to Remote APIs

During development, you may want to connect to staging or production API servers for testing authentication, profiles, or replays.

​
Staging API

Connect to staging servers: 
npm run dev:staging
This sets API_DOMAIN=api.openfront.dev.

​
Production API

Connect to production servers: 
npm run dev:prod
This sets API_DOMAIN=api.openfront.io.
To replay a production game, ensure you’re on the same git commit that the game was executed on. Find the gitCommit value at https://api.openfront.io/game/[gameId].

​
Development Workflow

​
Creating a Branch

Create a feature or bugfix branch: 
git checkout -b feature/your-feature-name

​
Code Quality Tools

OpenFront enforces code quality using ESLint and Prettier: 
npm run format
The project uses Husky and lint-staged to automatically format and lint code before commits.

​
Building the Project

npm run build-dev
The development build:
  • Runs TypeScript type checking
  • Builds with Vite in development mode
  • Outputs to /static directory
The production build:
  • Runs type checking with --kill-others-on-fail
  • Optimizes and minifies code
  • Splits vendor chunks for better caching

​
Project Structure

OpenFrontIO/
├── src/
│   ├── client/       # Frontend game client
│   │   ├── rendering/
│   │   ├── ui/
│   │   └── workers/
│   ├── core/         # Shared deterministic game logic
│   │   ├── intents/
│   │   ├── executions/
│   │   └── entities/
│   └── server/       # Backend game server
│       ├── lobby/
│       └── game/
├── resources/        # Static assets (images, maps, sounds)
├── tests/           # Unit and integration tests
├── map-generator/   # Go-based map generation tool
├── package.json     # npm dependencies and scripts
├── vite.config.ts   # Vite configuration
├── tsconfig.json    # TypeScript configuration
└── eslint.config.js # ESLint configuration

​
Development Ports

ServicePortDescription
Client (Vite)9000Frontend development server
Main Server3000Lobby and coordination server
Worker 03001Game server instance 1
Worker 13002Game server instance 2
Vite proxies WebSocket connections and API requests to the appropriate backend servers.

​
Environment Variables

Create a .env file in the project root for local configuration:
.env
# Skip automatic browser opening
SKIP_BROWSER_OPEN=true

# API domain (overrides default)
API_DOMAIN=api.openfront.dev

# Game environment
GAME_ENV=dev

# Stripe (if testing payments)
STRIPE_PUBLISHABLE_KEY=pk_test_...

​
Additional Tools

​
Map Generator

OpenFront includes a Go-based map generator: 
npm run gen-maps
This command:
  1. Runs the map generator in the /map-generator directory
  2. Generates new map data
  3. Automatically formats the output

​
Performance Testing

Run performance benchmarks: 
npm run perf

​
Troubleshooting

Make sure you’re using npm run inst instead of npm install. If issues persist, try:
rm -rf node_modules package-lock.json
npm run inst
If port 9000 or 3000 is already in use, kill the existing process:
# Find process on port 9000
lsof -ti:9000 | xargs kill -9

# Find process on port 3000
lsof -ti:3000 | xargs kill -9
Ensure you’re using the correct TypeScript version:
npx tsc --version
The project uses TypeScript 5.7.2 as specified in package.json.
Check that:
  1. The server is running (npm run start:server-dev)
  2. Vite proxy configuration is correct in vite.config.ts
  3. No firewall is blocking local connections

​
Getting Help

Discord Community

Join the development Discord for help

GitHub Issues

Report bugs or request features

​
Next Steps

Architecture

Understand OpenFront’s system design

Contributing

Learn how to contribute code

Testing

Write and run tests

Build docs developers (and LLMs) love

Get started for freeTalk to us