Quick start

InstallCopy Anchor Link

npm install ferrysync zod

Describe the dataCopy Anchor Link

The schema is one file, imported by the app and, later, by the server. Here a task belongs to a project, and a project is a space (the engine and the wire call it a group: same thing): the people in it see its tasks, and nobody else does. See Schema.

import { defineSchema } from 'ferrysync';
import { z } from 'zod';

export const schema = defineSchema(
  {
    projects: z.object({ id: z.string(), name: z.string() }),
    tasks: z.object({
      id: z.string(),
      projectId: z.string(),
      title: z.string(),
      done: z.boolean().default(false),
    }),
  },
  {
    spaces: {
      projects: (project) => `project:${project.id}`,
      tasks: (task) => `project:${task.projectId}`,
    },
  },
);

export type Project = typeof schema.$infer.projects;

Create the clientCopy Anchor Link

The client keeps the data in a local database on the device. Pick the storage of your platform:

import { createSync, indexedDbStorage } from 'ferrysync';

import { schema } from './schema';

export const sync = createSync({ schema, storage: indexedDbStorage('tasks') });

That is already a working app. Writes are plain function calls: they apply at once, return the row, and are saved on the device. There is no server yet, so there is nothing to wait for.

await sync.ready;

const trip = sync.projects.create({ name: 'Japan' });
const flights = sync.tasks.create({ projectId: trip.id, title: 'Book flights' });
sync.tasks.update(flights.id, { done: true });

Show it on screenCopy Anchor Link

Every query hands over its current result and each change to it, from the local database: nothing goes over the network, so there is no loading state per query. Pick your UI:

• React and React Native read through useQuery, which re-renders only when what it read changes. SyncProvider shows its fallback once, while the local data opens. It is not a fetching hook like TanStack Query's; using that too? Import Ferry's as useLiveQuery: see React.
• Without a framework, a query's get() and subscribe() are all there is to it.
• Vue, Svelte, Solid and the rest wrap the same two methods in a few lines: see your own bindings.

'use client';

import { SyncProvider, useQuery } from 'ferrysync/react';

import { type Project } from './schema';
import { sync } from './sync';

const ProjectTasks = ({ project }: { project: Project }) => {
  const tasks = useQuery(sync.tasks.where({ projectId: project.id }));
  const add = () => sync.tasks.create({ projectId: project.id, title: `Task ${tasks.length + 1}` });
  return (
    <section>
      <h2>{project.name}</h2>
      {tasks.map((task) => (
        <label key={task.id}>
          <input
            type="checkbox"
            checked={task.done}
            onChange={() => sync.tasks.update(task.id, { done: !task.done })}
          />
          {task.title}
        </label>
      ))}
      <button onClick={add}>Add a task</button>
    </section>
  );
};

const Projects = () => {
  const projects = useQuery(sync.projects.all());
  const add = () => sync.projects.create({ name: `Project ${projects.length + 1}` });
  return (
    <main>
      <button onClick={add}>New project</button>
      {projects.map((project) => (
        <ProjectTasks key={project.id} project={project} />
      ))}
    </main>
  );
};

export const TasksApp = () => (
  <SyncProvider sync={sync} fallback={<p>Opening…</p>}>
    <Projects />
  </SyncProvider>
);

Render <TasksApp /> anywhere in your React app, or load main.ts in a page with a #app element. Close it and open it again: the projects and tasks are still there. Without a server, the device is the only copy, and that is a fine way to start.

Add a serverCopy Anchor Link

To share the data between devices, add the server. It is a library inside your backend, over your database. Everyone is the same user for now; Accounts is where yours come in.

import { createSyncServer, nodeSqlite, sqliteStore } from 'ferrysync/server';
import { DatabaseSync } from 'node:sqlite';

import { schema } from './schema';

export const syncServer = createSyncServer({
  schema,
  store: sqliteStore(nodeSqlite(new DatabaseSync('sync.db'))),
  auth: () => 'demo-user',
  // Whoever creates a project becomes the first member of its space.
  claimSpace: ({ table, space, row }) => table === 'projects' && space === `project:${row.id}`,
});

Then mount it on one route of the framework you already have. It answers every Ferry request (push, pull, bootstrap and wait) by the last segment of the path:

import { syncServer } from '../../../../sync-server';

export const POST = syncServer.fetch;

Connect the clientCopy Anchor Link

One option links the client to that route: backend, with the URL where you mounted it, without the endpoint at the end.

import { createSync, http, indexedDbStorage } from 'ferrysync';

import { schema } from './schema';

export const sync = createSync({
  schema,
  storage: indexedDbStorage('tasks'),
  backend: http({ url: '/api/sync' }),
});

Nothing else changes. Writes still apply at once on the device; now they also wait in an outbox and reach the server in the background, and changes from other devices arrive as they happen.

See it workCopy Anchor Link

Each check proves one part of what you built:

1. It syncs. Open the app in a second window or on a second device. The projects and tasks are there, and a task you tick on one is ticked on the other a moment later.
2. It works offline. Cut one off: in the browser, developer tools, then Network, then Offline; on a phone, airplane mode. Add and tick tasks: they apply at once, as before.
3. Nothing is lost. Reload the app, or close and reopen it, while it is still offline. The changes are there, waiting in the outbox.
4. It catches up. Bring the network back. Within a moment the other window shows every change you made offline.
5. The server keeps it. Restart the server. Everything is in its database, and both apps carry on where they were.

If all five pass, you have the whole of Ferry running: a local database, an outbox, a server that orders the changes, and realtime between devices. The Overview shows each part step by step, with a playground to break it in.