Tutorial

In this tutorial, you’ll build a todo application that works offline and syncs automatically when reconnected. Offline-first apps are essential for mobile users and anyone with unreliable connections. Your app stays responsive even without internet, and changes from multiple users merge seamlessly when connectivity returns.

Step 1: Create the Project

mizu new synctodo --template sync
cd synctodo
go mod tidy
mizu dev

Open http://localhost:8080 to see the default syncing todo app.

Step 2: Understand the Default App

The template includes a working todo list. Let’s trace how data flows.

The Store

Look at service/todo/mutator.go:

type Store struct {
    mu    gosync.RWMutex
    todos map[string]map[string]*Todo // scope -> id -> todo
}

type Todo struct {
    ID        string `json:"id"`
    Title     string `json:"title"`
    Completed bool   `json:"completed"`
}

The store uses a mutex for thread safety and organizes todos by scope (like a namespace).

The Apply Function

This is the heart of sync - it processes mutations:

func (s *Store) Apply(ctx context.Context, m sync.Mutation) ([]sync.Change, error) {
    switch m.Type {
    case "todo.create":
        return s.createTodo(scope, m.Args)
    case "todo.toggle":
        return s.toggleTodo(scope, m.Args)
    case "todo.delete":
        return s.deleteTodo(scope, m.Args)
    }
    return nil, fmt.Errorf("unknown mutation: %s", m.Type)
}

Each mutation type maps to a specific operation.

The Snapshot Function

Returns current state for new clients:

func (s *Store) Snapshot(ctx context.Context, scope string) (json.RawMessage, uint64, error) {
    todos := s.GetAll(scope)
    data, _ := json.Marshal(todos)
    return data, 0, nil
}

Step 3: Test Offline Behavior

Open the app in your browser
Add some todos
Open DevTools → Network → check “Offline”
Add more todos (they appear immediately!)
Uncheck “Offline”
Watch todos sync to server

The key insight: the UI updates before the server confirms.

Step 4: Add Priority Feature

Let’s add priority levels to todos.

Update the Model

Edit service/todo/mutator.go:

type Todo struct {
    ID        string `json:"id"`
    Title     string `json:"title"`
    Completed bool   `json:"completed"`
    Priority  string `json:"priority"` // "low", "medium", "high"
}

Update Create Function

func (s *Store) createTodo(scope string, args json.RawMessage) ([]sync.Change, error) {
    var input struct {
        ID       string `json:"id"`
        Title    string `json:"title"`
        Priority string `json:"priority"`
    }
    if err := json.Unmarshal(args, &input); err != nil {
        return nil, err
    }

    // Default priority
    priority := input.Priority
    if priority == "" {
        priority = "medium"
    }

    todo := &Todo{
        ID:        input.ID,
        Title:     input.Title,
        Completed: false,
        Priority:  priority,
    }
    s.todos[scope][todo.ID] = todo

    data, _ := json.Marshal(s.todos[scope])
    return []sync.Change{{Scope: scope, Data: data}}, nil
}

Add Set Priority Mutation

func (s *Store) Apply(ctx context.Context, m sync.Mutation) ([]sync.Change, error) {
    s.mu.Lock()
    defer s.mu.Unlock()

    scope := m.Scope
    if s.todos[scope] == nil {
        s.todos[scope] = make(map[string]*Todo)
    }

    switch m.Type {
    case "todo.create":
        return s.createTodo(scope, m.Args)
    case "todo.toggle":
        return s.toggleTodo(scope, m.Args)
    case "todo.delete":
        return s.deleteTodo(scope, m.Args)
    case "todo.setPriority":
        return s.setPriority(scope, m.Args)
    default:
        return nil, fmt.Errorf("unknown mutation: %s", m.Type)
    }
}

func (s *Store) setPriority(scope string, args json.RawMessage) ([]sync.Change, error) {
    var input struct {
        ID       string `json:"id"`
        Priority string `json:"priority"`
    }
    if err := json.Unmarshal(args, &input); err != nil {
        return nil, err
    }

    todo := s.todos[scope][input.ID]
    if todo == nil {
        return nil, fmt.Errorf("todo not found: %s", input.ID)
    }

    todo.Priority = input.Priority

    data, _ := json.Marshal(s.todos[scope])
    return []sync.Change{{Scope: scope, Data: data}}, nil
}

Update the JavaScript Client

Edit assets/js/sync.js to handle priority:

class SyncClient {
    constructor(url, scope) {
        this.url = url;
        this.scope = scope;
        this.pending = [];
        this.state = [];
    }

    async createTodo(title, priority = 'medium') {
        await this.mutate('todo.create', {
            id: crypto.randomUUID(),
            title,
            priority,
        });
    }

    async setPriority(id, priority) {
        await this.mutate('todo.setPriority', { id, priority });
    }

    async mutate(type, args) {
        const mutation = {
            id: crypto.randomUUID(),
            type,
            args,
            scope: this.scope,
        };

        // Optimistic update
        this.applyLocal(mutation);
        this.render();

        // Queue and sync
        this.pending.push(mutation);
        await this.sync();
    }

    applyLocal(mutation) {
        switch (mutation.type) {
        case 'todo.create':
            this.state.push({
                id: mutation.args.id,
                title: mutation.args.title,
                completed: false,
                priority: mutation.args.priority || 'medium',
            });
            break;
        case 'todo.setPriority':
            const todo = this.state.find(t => t.id === mutation.args.id);
            if (todo) todo.priority = mutation.args.priority;
            break;
        }
    }

    render() {
        const container = document.getElementById('todos');
        container.innerHTML = this.state
            .sort((a, b) => this.priorityOrder(a) - this.priorityOrder(b))
            .map(todo => `
                <div class="todo priority-${todo.priority}">
                    <span>${todo.title}</span>
                    <select onchange="sync.setPriority('${todo.id}', this.value)">
                        <option value="low" ${todo.priority === 'low' ? 'selected' : ''}>Low</option>
                        <option value="medium" ${todo.priority === 'medium' ? 'selected' : ''}>Medium</option>
                        <option value="high" ${todo.priority === 'high' ? 'selected' : ''}>High</option>
                    </select>
                </div>
            `).join('');
    }

    priorityOrder(todo) {
        return { high: 0, medium: 1, low: 2 }[todo.priority];
    }

    async sync() {
        if (this.pending.length === 0) return;

        try {
            const res = await fetch(this.url + '/_sync/push', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    scope: this.scope,
                    mutations: this.pending,
                }),
            });

            if (res.ok) {
                const { changes } = await res.json();
                if (changes && changes.length > 0) {
                    this.state = JSON.parse(changes[0].data);
                    this.render();
                }
                this.pending = [];
            }
        } catch (e) {
            console.log('Sync failed, will retry:', e);
        }
    }
}

// Initialize
const sync = new SyncClient('', 'default');

Step 5: Add Conflict Resolution

When two users edit the same todo, we need to handle conflicts.

Last-Write-Wins Strategy

The simplest approach - later mutations win:

func (s *Store) setPriority(scope string, args json.RawMessage) ([]sync.Change, error) {
    var input struct {
        ID        string `json:"id"`
        Priority  string `json:"priority"`
        Timestamp int64  `json:"timestamp"`
    }
    if err := json.Unmarshal(args, &input); err != nil {
        return nil, err
    }

    todo := s.todos[scope][input.ID]
    if todo == nil {
        return nil, fmt.Errorf("todo not found: %s", input.ID)
    }

    // Only apply if newer (last-write-wins)
    if input.Timestamp > todo.UpdatedAt {
        todo.Priority = input.Priority
        todo.UpdatedAt = input.Timestamp
    }

    data, _ := json.Marshal(s.todos[scope])
    return []sync.Change{{Scope: scope, Data: data}}, nil
}

Update the Todo struct:

type Todo struct {
    ID        string `json:"id"`
    Title     string `json:"title"`
    Completed bool   `json:"completed"`
    Priority  string `json:"priority"`
    UpdatedAt int64  `json:"updatedAt"`
}

Step 6: Add Multi-User Support

Open the app in two browser windows to test collaboration.

Add User Tracking

// In app/server/app.go
func (a *App) setupSync() {
    log := memory.NewLog()
    dedupe := memory.NewDedupe()

    a.syncEngine = sync.New(sync.Options{
        Log:      log,
        Apply:    a.store.Apply,
        Snapshot: a.store.Snapshot,
        Dedupe:   dedupe,
        OnChange: func(scope string, changes []sync.Change) {
            // Broadcast to all connected clients via live server
            for _, change := range changes {
                a.liveServer.Publish(scope, "sync", change.Data)
            }
        },
    })
}

Client Listens for Updates

class SyncClient {
    constructor(url, scope) {
        this.url = url;
        this.scope = scope;
        this.pending = [];
        this.state = [];
        this.connectWebSocket();
    }

    connectWebSocket() {
        this.ws = new WebSocket(`ws://${location.host}/ws`);
        this.ws.onmessage = (e) => {
            const { topic, data } = JSON.parse(e.data);
            if (topic === 'sync') {
                this.state = JSON.parse(data);
                this.render();
            }
        };
        this.ws.onopen = () => {
            // Subscribe to our scope
            this.ws.send(JSON.stringify({
                topic: 'subscribe',
                data: this.scope,
            }));
        };
        this.ws.onclose = () => {
            setTimeout(() => this.connectWebSocket(), 1000);
        };
    }
}

How Sync Works

User A (offline)              Server                User B (online)
     |                          |                        |
     | --- Create todo -------- | (queued locally)       |
     |                          |                        |
     | (goes online)            |                        |
     |                          |                        |
     | --- Push mutations ----> |                        |
     |                          | --- Apply -----------> |
     |                          | --- Broadcast -------> |
     |                          |                        | (UI updates)
     | <-- Confirm ------------ |                        |
     |                          |                        |

What You Learned

Mutation-based data changes
Optimistic UI updates
Offline queueing and sync
Conflict resolution strategies
Multi-user broadcasting

Getting Started

Commands

Templates Overview

Minimal Template

API Template

Contract Template

Web Template

Live Template

Sync Template

Reference

Step 1: Create the Project

Step 2: Understand the Default App

The Store

The Apply Function

The Snapshot Function

Step 3: Test Offline Behavior

Step 4: Add Priority Feature

Update the Model

Update Create Function

Add Set Priority Mutation

Update the JavaScript Client

Step 5: Add Conflict Resolution

Last-Write-Wins Strategy

Step 6: Add Multi-User Support

Add User Tracking

Client Listens for Updates

How Sync Works

What You Learned

Next Steps

Sync Documentation

Live Template

Getting Started

Commands

Templates Overview

Minimal Template

API Template

Contract Template

Web Template

Live Template

Sync Template

Reference

​Step 1: Create the Project

​Step 2: Understand the Default App

​The Store

​The Apply Function

​The Snapshot Function

​Step 3: Test Offline Behavior

​Step 4: Add Priority Feature

​Update the Model

​Update Create Function

​Add Set Priority Mutation

​Update the JavaScript Client

​Step 5: Add Conflict Resolution

​Last-Write-Wins Strategy

​Step 6: Add Multi-User Support

​Add User Tracking

​Client Listens for Updates

​How Sync Works

​What You Learned

​Next Steps

Sync Documentation

Live Template

Step 1: Create the Project

Step 2: Understand the Default App

The Store

The Apply Function

The Snapshot Function

Step 3: Test Offline Behavior

Step 4: Add Priority Feature

Update the Model

Update Create Function

Add Set Priority Mutation

Update the JavaScript Client

Step 5: Add Conflict Resolution

Last-Write-Wins Strategy

Step 6: Add Multi-User Support

Add User Tracking

Client Listens for Updates

How Sync Works

What You Learned

Next Steps