How to use boardgame.io: install, build and run a turn-based game

What boardgame.io does and who it is for

boardgame.io is an engine, not a finished game. You write functions that describe how the game state changes when a particular move is made, and the library converts them into a game that can be played. According to the README, this includes online multiplayer and state syncing across clients and the server, so you do not write networking or storage code yourself.

It suits developers building turn-based board or card games for the browser, people prototyping rules before building a full interface, and developers using React or React Native who want a ready-made game client binding. It is not a good fit for real-time action games, because the project focuses on turn-based play, and it is used through code, so non-programmers will find it hard to use.

• State management across clients, server and storage
• Multiplayer state kept in sync
• Automatically generated bots (AI)
• Game phases with different rules and turn orders
• Lobby for matchmaking and game creation
• Prototyping interface to simulate moves before rendering
• Plugin system for extending the engine
• View-layer agnostic: vanilla JS client or React and React Native bindings
• Game logs with time travel to earlier states

Install boardgame.io with npm

The README lists Node.js and npm as the prerequisites. Install the library from the npm registry in your project folder with the command below.

The full documentation at boardgame.io/documentation covers project setup in more detail.

Define the game state and moves

The core idea is that you write functions describing how state changes when a player makes a move. Each move receives the current state and returns the updated state, and the engine handles the rest, including keeping clients in sync.

The README does not include a full code example, so consult the documentation for the exact game definition format and API.

• Write a move as a function that describes the state change
• Let the engine manage syncing between clients and the server
• Use game phases when different rules or turn orders apply

Prototype rules before building the interface

The library includes an interface for simulating moves before you render the game. This lets you test rule logic early, before investing in a full user interface.

Because the engine is view-layer agnostic, you can later attach the vanilla JS client or the React or React Native bindings.

Add multiplayer and lobby features

The README says game state is kept in sync in realtime and across platforms, and that a lobby handles player matchmaking and game creation. You do not need to write your own networking layer to get these features.

Use the official documentation and the project's Gitter channel or GitHub Discussions for questions about setting up multiplayer.

Learn the project's resources and get help

The main documentation is at boardgame.io/documentation. The project also has a changelog in docs/documentation/CHANGELOG.md, a Gitter channel, and GitHub Discussions. Bugs can be reported through GitHub issues.

To explore working code, the README says examples are in the examples folder of the repository. Run them with npm install followed by npm start from the repository root.