# Sync

Say which rows a person may see. The browser keeps a copy of them, writes at once, and syncs when the network is there.

Hosts: Node, Docker, Cloudflare, Vercel, Netlify.

```ts [server/sync/todos.ts] fragment
import { defineSync } from 'vite-hub/sync'
import { todos } from '../databases/default'

// One file is one synced table, at /api/_vitehub/sync/todos
export default defineSync({
  table: todos,
  where: ({ user }) => user ? { ownerId: user.id } : false,
})
```

```vue [app/pages/todos.vue] fragment
<script setup lang="ts">
const todos = useSync('todos')
const title = ref('')
</script>

<!-- Rows show at once, also offline and after a reload -->
<template>
  <form @submit.prevent="todos.insert({ title }); title = ''">
    <input v-model="title">
  </form>
  <ul>
    <li v-for="todo in todos.rows" :key="todo.id">
      <input type="checkbox" :checked="todo.done" @change="todos.update(todo.id, { done: !todo.done })">
      {{ todo.title }}
    </li>
  </ul>
  <p v-if="todos.queued">{{ todos.queued }} changes wait for the network</p>
</template>
```

```bash [terminal]
# The synced tables, and the last changes of one
vitehub sync list
vitehub sync changes todos
```

## What you get

| Part | What it does |
| --- | --- |
| Local copy | The browser keeps the rows in IndexedDB. A reload shows them at once, then pulls what changed. |
| Writes at once | `insert`, `update`, and `delete` change `rows` at once. Each write goes to a queue in IndexedDB before it is sent, so it survives offline time, a reload, and a crash. |
| Order | One push at a time, with the writes in the order you made them. Two updates of one row apply in that order. |
| Scope | `where` returns the rows that the caller may see, such as `{ ownerId: user.id }` or the caller's teams, `{ teamId: ['design', 'web'] }`. The server filters reads with it, writes its values into inserts, and refuses writes outside it. |
| Moved rows | A row that is deleted or moves to another team leaves the devices of the old team, and reaches only the new team. |
| Subsets | `useSync('comments', { where: { issueId } })` syncs a part of the rows, with its own local copy, on the columns that `subsets` lists. A second visit shows it from the device. |
| Actions | Named writes with server logic, such as `cards.actions.rate({ id, stars })`, on the same queue and change log as row writes. `refuse(message)` stops one. |
| Live | Each tab keeps one live stream open for all its synced tables, so other people's changes show within about a second. |
| Account guard | Each write keeps the account that made it. After a sign-in as another person, old writes wait until their account signs in again. An app with its own sign-in returns the user from `identify`. |
| Once only | Each write has an id. When an answer is lost and the client sends the write again, the server does not apply it twice. |
| Fresh rows | The client pulls on start, when the page shows again, when the network comes back, and after each write, besides the live stream. Other tabs see a change at once. When the table changes, the browser drops its stored rows and keeps its queued writes. |
| Inspection | `vitehub sync list` and `vitehub sync changes <name>`, and the `sync.list` and `sync.changes` operations. |

The client needs no framework. Vue gets `useSync()`, and other frameworks use the same store through `createSync()`.

## Sync, Database, or Realtime

Does each person or team work on their own rows in the browser? Then use Sync. Does only server code read and write the table? Then use [Database](https://vitehub.dev/docs/database). Do people send short messages or show who is online in a room? Then use [Realtime](https://vitehub.dev/docs/realtime).

## Next

- [Get started](https://vitehub.dev/docs/sync/get-started): a todo list that works offline.
- [Server API](https://vitehub.dev/docs/sync/server-api): every option of `defineSync()`, team scopes, subsets, actions, live pulls, and the CLI.
- [Limits and errors](https://vitehub.dev/docs/sync/limits-and-errors): what Sync does not do, and the `SYNC_*` codes.
- [Vue](https://vitehub.dev/docs/sync/vue): `useSync()`, failures, and sign-out.

<!-- vitehub-docs:section-links -->
## In this section

- [Overview](https://vitehub.dev/raw/docs/sync.md) (this page)
- [Get started](https://vitehub.dev/raw/docs/sync/get-started.md)
- [Server API](https://vitehub.dev/raw/docs/sync/server-api.md)
- [Limits and errors](https://vitehub.dev/raw/docs/sync/limits-and-errors.md)
- [Vue](https://vitehub.dev/raw/docs/sync/vue.md)

Next: [SYNC_ACCOUNT_CHANGED](https://vitehub.dev/raw/docs/sync/diagnostics/sync_account_changed.md)

All pages: [llms.txt](https://vitehub.dev/llms.txt)
