Quick start

Get a multiplayer counter running from scratch. This guide covers installation, provider setup, and your first useSyncState hook.

Prerequisites

This guide assumes you have an existing Robo project. If not, create one first with npx create-robo my-project.

Setup

Install the plugin

npx robo add @robojs/sync@next

Also install @robojs/server if you haven't:

npx robo add @robojs/server@next

Wrap your app

Add SyncContextProvider at the top of your component tree. Pass clientData to attach metadata visible to other clients.

src/app/App.tsx

import { SyncContextProvider } from '@robojs/sync'

export function App() {
	return (
		<SyncContextProvider clientData={{ name: 'Player1' }}>
			<Counter />
		</SyncContextProvider>
	)
}

src/app/App.jsx

import { SyncContextProvider } from '@robojs/sync'

export function App() {
	return (
		<SyncContextProvider clientData={{ name: 'Player1' }}>
			<Counter />
		</SyncContextProvider>
	)
}

Create a synced component

Use useSyncState to share state across all connected clients. The third return value provides context about connected clients and host status.

src/app/Counter.tsx

import { useSyncState } from '@robojs/sync'

export function Counter() {
	const [count, setCount, context] = useSyncState(0, ['counter'])

	return (
		<div>
			<h1>Count: {count}</h1>
			<button onClick={() => setCount(count + 1)}>Increment</button>
			<p>Players: {context.clients.length}</p>
			<p>{context.isHost ? 'You are the host' : 'Guest'}</p>
		</div>
	)
}

src/app/Counter.jsx

import { useSyncState } from '@robojs/sync'

export function Counter() {
	const [count, setCount, context] = useSyncState(0, ['counter'])

	return (
		<div>
			<h1>Count: {count}</h1>
			<button onClick={() => setCount(count + 1)}>Increment</button>
			<p>Players: {context.clients.length}</p>
			<p>{context.isHost ? 'You are the host' : 'Guest'}</p>
		</div>
	)
}

Run your project

npx robo dev

Open multiple browser tabs to see the counter sync in real-time. The first tab becomes the host.

How it works

useSyncState takes an initial value and a key array.
Components sharing the same key see the same state.
The third return value provides context: connected clients, host status, and messaging functions.
State syncs automatically via WebSocket. No manual handling needed.

Next Steps

useSyncState

Deep dive into the core sync hook.

useSyncContext

Track connected clients and host status.

Server handlers

Add server-side validation and game logic.

Quick start

useSyncState

useSyncContext

Server handlers

On this page