Quick Start
You'll run a GoSync server locally, connect a web app to it, and watch data sync between tabs.
1. Run a server
Download the server for your platform from the latest release and start it in demo mode:
# Linux (on a Mac, use gosync_Darwin_arm64.tar.gz or gosync_Darwin_x86_64.tar.gz)
curl -L -o gosync.tar.gz https://github.com/HarshalPatel1972/GoSync/releases/latest/download/gosync_Linux_x86_64.tar.gz
tar -xzf gosync.tar.gz
GOSYNC_INSECURE_DEV_AUTH=true ./gosync-server
On Windows (PowerShell):
Invoke-WebRequest https://github.com/HarshalPatel1972/GoSync/releases/latest/download/gosync_Windows_x86_64.zip -OutFile gosync.zip
Expand-Archive gosync.zip -DestinationPath gosync
$env:GOSYNC_INSECURE_DEV_AUTH="true"; .\gosync\gosync-server.exe
The server listens on http://localhost:8080 and stores data in gosync.db.
Demo mode only:
GOSYNC_INSECURE_DEV_AUTH=trueaccepts any string as a user's token. Never use it in production. Server Setup shows how to plug in real authentication.
2. Install the client
npm install @harshalpatel2868/gosync-client
Version 2.0.1 or later works out of the box with Vite and Next.js (both Turbopack and webpack):
the WebAssembly engine is picked up automatically. These setups are tested on every change. With
another bundler, if the engine fails to load, copy gosync.wasm and wasm_exec.js from the
package into your public folder and pass wasmUrl (see the API reference).
3. Connect
import { createClient } from '@harshalpatel2868/gosync-client';
const userId = 'alice'; // in demo mode, the token is just a user name
const db = await createClient({
url: 'ws://localhost:8080/sync',
getToken: () => userId, // in production: return a JWT from your auth provider
dbName: `myapp-${userId}`, // one local database per signed-in user
});
4. Read and write
Writes go to the local database immediately, work offline, and sync in the background.
// Create or update. Only the fields you pass are changed.
await db.set('todos', crypto.randomUUID(), { title: 'Buy milk', done: false });
// Update one field
await db.set('todos', id, { done: true });
// Read (always from the local database: instant, works offline)
const todo = await db.get('todos', id); // { id, title, done } or null
const todos = await db.list('todos'); // [{ id, ... }, ...]
// Delete
await db.delete('todos', id);
Values can be any JSON: strings, numbers, booleans, arrays, nested objects or null.
5. Keep your UI in sync
watch calls you immediately and again whenever the collection changes, whether the change was
local, from another tab, or from another device.
const stop = db.watch('todos', (todos) => render(todos));
db.onStatus((status) => {
// 'offline' | 'connecting' | 'online'
document.querySelector('#status').textContent = status;
});
db.onError((err) => console.warn(err.message)); // e.g. a write the server rejected
6. Try it
Open your app in two tabs and add a todo in one: it appears in the other instantly. Stop the server, keep adding todos (they're saved locally), restart it, and watch everything sync.
Using React?
Create the client once, in the browser only:
'use client';
import { useEffect, useState } from 'react';
import { createClient } from '@harshalpatel2868/gosync-client';
export function useTodos(userId, getToken) {
const [todos, setTodos] = useState([]);
useEffect(() => {
let db;
let cancelled = false;
createClient({ url: 'wss://sync.example.com/sync', getToken, dbName: `app-${userId}` }).then((client) => {
if (cancelled) return client.close(); // unmounted while loading
db = client;
db.watch('todos', setTodos);
});
return () => {
cancelled = true;
db?.close(); // close() also stops watch()
};
}, [userId, getToken]);
return todos;
}