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:

bash
# 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):

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=true accepts 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

bash
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

javascript
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.

javascript
// 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.

javascript
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:

javascript
'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;
}

Next: Set up your server for production โ†’