# boardgame.io: a turn-based game engine that hides the networking layer

> boardgame.io is an MIT-licensed TypeScript engine where you describe game state transitions as functions and the library supplies multiplayer sync, bots, phases and a lobby. It fits small turn-based games; it is not a realtime engine.

**boardgameio/boardgame.io** — State Management and Multiplayer Networking for Turn-Based Games. View-layer Agnostic: Use the vanilla JS client or the bindings for React / React Native.

- Repository: https://github.com/boardgameio/boardgame.io
- Website: https://boardgame.io
- Stars: 12,439 · Forks: 831
- Language: TypeScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/boardgameio-boardgame-io

## The problem boardgame.io removes: writing a game server

A turn-based game has an awkward amount of infrastructure attached to it. You need a place where the authoritative state lives, a way to validate that a move is legal for the player who sent it, a channel to push the new state to every other player, and some storage so a match survives a restart. None of that is the game. It is the part people abandon projects over.

boardgame.io's pitch is that you write the rules and it writes the rest. The README describes it as "an engine for creating turn-based games using JavaScript" and claims that the move functions you write are "automatically converted into a playable game complete with online multiplayer features, all without requiring you to write a single line of networking or storage code." That is the whole value proposition in one sentence, and it is also the boundary of the tool.

The audience is narrow and specific. It suits a solo developer or a small team building a card game, a board game port, a turn-based strategy prototype, or a classroom exercise in game state modelling. It does not suit anyone building an action game, a physics sandbox, or a game where the server needs custom matchmaking logic beyond what the lobby provides. The repository's own examples folder points at the intended shape: examples/react-web, examples/react-native and examples/snippets.

## How the engine turns move functions into a running game

The mechanism described in the documentation is a reducer, in the same sense as Redux. You define a game object with a setup function that returns the initial state, and a moves object whose entries are functions. Each move receives a context object and the current state, and mutates the state in place. The engine wraps that in its own flow layer, which decides whose turn it is, which moves are currently legal, and what happens when a turn ends.

The flow layer is where the project's distinctive abstractions live. Phases let you define different rules and turn orders for different parts of a game, so a setup phase and a scoring phase can have separate move sets and separate end conditions. A plugin system allows new abstractions to be layered on top of the core, and the README lists logs as a first-class feature: game logs with time travel, meaning you can view the board at an earlier state.

State synchronisation is the other half. The README states that game state "is managed seamlessly across clients, server and storage automatically" and that it "is kept in sync in realtime and across platforms." The practical consequence is that your client code reads state and dispatches moves, and the engine decides whether the dispatch goes to a local reducer or over the network. The vanilla JS client and the React and React Native bindings are all views onto the same store, which is why the project describes itself as view-layer agnostic.

Bots are generated rather than hand-written. The README lists "automatically generated bots that can play your game" as a feature, which follows from the move functions being enumerable: if the engine knows every legal move and can simulate the result, it can search. This is a real benefit for testing, because you can run a game to completion without a human.

## Installing boardgame.io and running a first game

The README gives one installation command. It assumes Node and npm are already present.

```bash
npm install boardgame.io
```

After that, the documented path is the full documentation site rather than the README, which links to https://boardgame.io/documentation/. The README does not include a minimal game definition, so the shape of a game is described in prose here rather than shown as a snippet: a game object carries a setup function returning the initial state and a moves object whose functions mutate that state, and the React binding is imported from the package and given the game object as a prop.

If you want to see the engine working before writing any of your own code, the README documents running the bundled examples from a clone of the repository:

```bash
npm install
npm start
```

The README states that the examples can be found in the examples folder. The package.json shows the start script running a dev server and a dev client in parallel, with the server entry point at examples/react-web/server.js, so the browser example is the fastest thing to look at.

## Where boardgame.io stops being the right tool

The engine assumes turn-based. Every abstraction in it, from phases to turn order to the move dispatch, is built around the idea that one player acts at a time and that the state between actions is stable. If your game needs continuous simulation, or two players acting in the same tick, you are working against the model rather than with it.

The second limitation is that the engine owns your state shape. Because moves mutate the state in place and the flow layer serialises it for transport and storage, anything you put in that state has to survive the round trip. Closures, class instances with methods, and references to DOM nodes are not going to behave the way they do in a local object. This is a constraint the README does not spell out; it is implied by the claim that state is managed across clients, server and storage automatically.

The third is customisation depth. The lobby is described as player matchmaking and game creation, which is useful but generic. If you need ranked matchmaking, skill-based pairing, or a persistence layer with specific query patterns, you will be extending or bypassing the provided pieces. The README does not document rollback, and it does not document how to swap the storage backend, so those are questions to take to the documentation site or the Gitter channel rather than the README.

Finally, the repository package.json shows version 0.50.2. A zero-major version number is a signal about API stability, and anyone planning a long-lived project should read the changelog at docs/documentation/CHANGELOG.md before picking a version to pin.

## boardgame.io compared with a general realtime backend

The obvious alternative is to build on a general realtime synchronisation layer such as a hosted websocket service or a database with live queries, and write the game rules yourself. The difference is where the abstraction sits.

A realtime backend synchronises whatever data you give it. It has no concept of a legal move, whose turn it is, or what a phase transition means. You get a channel and a conflict resolution story, and you write the rest, including the reducer, the validation and the turn logic. That is more work, but it is also more freedom: nothing constrains your state shape, and you can model simultaneous action if you need it.

boardgame.io inverts this. It gives you the turn logic and the move validation as the primary interface, and treats the network as an implementation detail you do not touch. The cost is that the engine's model of a game is now your model of a game. You cannot easily express something the flow layer does not anticipate.

A second alternative, for people who only want the state management and not the multiplayer, is to use a plain reducer library and skip the engine entirely. If your game is single-player or hot-seat, boardgame.io's networking features are dead weight, though the phases and bot generation may still earn their place.

## Maintenance, licensing and the cost of upgrading

The project is MIT licensed, which is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and licence text are preserved. That is a description of the licence terms, not legal advice; if your organisation has specific requirements around attribution or patent grants, have someone qualified read the LICENSE file.

The repository is not archived. The last push date was not available, so no claim can be made here about how frequently it is updated. What can be said is that the package.json pins the package manager to pnpm@10.16.0 and the repository uses a pnpm workspace with a packages directory and a subpackages.js file, so the build is a monorepo build rather than a single-package build. Contributing or forking means understanding that layout.

Upgrade cost is the real unknown. The version is 0.50.2, which in semver terms means every minor bump can carry a breaking change. The repository ships a changelog at docs/documentation/CHANGELOG.md, and that file is the thing to read before moving between versions. There is also a Python directory in the repository root, which suggests bindings or tooling for Python exist in the tree, but the README does not document them, so treat that as something to investigate rather than a supported surface.

## Conclusion

Adopt boardgame.io if your game is turn-based, your rules can be written as move functions, and you want the multiplayer plumbing handled for you. Skip it if you need realtime simulation or simultaneous action, or if you intend to write your own server-authoritative loop. Before committing, verify the published version on npm against the 0.50.2 in the repository package.json, read the changelog at docs/documentation/CHANGELOG.md for breaking changes between releases, and confirm the examples under examples/react-web run locally after npm install and npm start.

## FAQ

### how to install boardgame io

The README gives a single command: npm install boardgame.io. To run the bundled examples instead, clone the repository and run npm install followed by npm start; the README states the examples live in the examples folder.

### what is boardgame io

It is an engine for creating turn-based games using JavaScript, according to the README. You write functions describing how state changes on a move, and the engine converts that into a playable game with online multiplayer, bots, phases and a lobby.

### how to use boardgame io

You define a game object with a setup function returning initial state and a moves object whose functions mutate that state. The README points to the full documentation site for the details, and the repository ships examples under examples/react-web, examples/react-native and examples/snippets.

## Sources

- [Official documentation](https://boardgame.io)
- [Official README](https://github.com/boardgameio/boardgame.io#readme)
- [Project repository](https://github.com/boardgameio/boardgame.io)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/boardgameio-boardgame-io