Development Setup

Set up your local development environment for OpenFront

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

npm run start:client

vite

The client will be available at http://localhost:9000.

Server Only

Run just the game server:

Development

npm run start:server-dev

npm run start:server

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:

Feature

git checkout -b feature/your-feature-name

git checkout -b fix/issue-number-bug-name

Code Quality Tools

OpenFront enforces code quality using ESLint and Prettier:

Format Code

npm run format

npm run lint

npm run lint:fix

The project uses Husky and lint-staged to automatically format and lint code before commits.

Building the Project

Development Build

npm run build-dev

npm run build-prod

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

Service	Port	Description
Client (Vite)	9000	Frontend development server
Main Server	3000	Lobby and coordination server
Worker 0	3001	Game server instance 1
Worker 1	3002	Game 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

Dependencies not installing correctly

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

Port already in use

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

TypeScript errors

Ensure you’re using the correct TypeScript version:

npx tsc --version

The project uses TypeScript 5.7.2 as specified in package.json.

WebSocket connection issues

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