Offline Sync
Works offline is a property of a resource, not of a client. One engine, one wire protocol, and three storage adapters, so the same resource behaves the same way in a browser, on a phone and in the desktop app.
The Go API has served /api/sync/pull and /api/sync/push since v3.60, and grit generate resource registers every model with the sync registry as it generates it. The server side has been ready for a while. What was missing until v3.148.0 was a client outside apps/desktop.
grit add offline
That writes packages/sync and adds it to whichever of apps/web, apps/admin and apps/expo your project has. By default it mirrors every model the API registered, read out of routes.go rather than from a list that can go stale. Narrow it with --models products,orders.
What it does
Three things, and it is worth being precise about each.
A mirror. Every row the client has pulled, kept locally. Reads come from the mirror, so a list renders at the same speed and through the same code whether or not there is a network.
An outbox. Every local change that has not reached the server. At most one entry per row: a second edit to the same record squashes into the entry already waiting, so the outbox stays proportional to the rows you touched rather than the edits you made. Creating a row and then deleting it cancels both ends, rather than sending the server a delete for something it has never seen.
A version check. Every push carries the version the client believes the server holds. If they disagree, the server answers VERSION_CONFLICT with its current row attached, so a merge UI has both sides without a second round trip. The conflicted change is parked rather than retried, because replaying it would overwrite exactly the state the user is being asked about.
Using it
useOfflineResource is the hook that makes the promise concrete. It returns rows from the mirror and writes through the outbox, and the calling screen does not branch on connectivity anywhere.
"use client";import { useOfflineResource, useSyncStatus } from "@myapp/sync/react";export default function ProductsPage() {const { data, loading, create, update, remove } = useOfflineResource<Product>("products");const { state, pending, syncNow } = useSyncStatus();return (<div><SyncBadge state={state} pending={pending} onSync={syncNow} />{loading ? <Spinner /> : <ProductTable rows={data} onDelete={remove} />}{/* Returns an id immediately, whether it reached the server or the outbox */}<NewProductForm onSubmit={(values) => create(values)} /></div>);}
useSyncStatus gives you the badge: synced, syncing, offline or conflict, with the pending count and the time of the last successful sync.
Conflicts
useSyncConflicts returns the changes waiting for a decision, each carrying both the local values and the server's. There are two ways to end one: resolve with the merged row, which replays it claiming the version the user actually saw, or revert, which discards the local change and puts the server's version back.
const { conflicts, resolve, revert } = useSyncConflicts();return conflicts.map((c) => (<ConflictRowkey={c.model + c.entityId}mine={c.data}theirs={c.serverData}message={c.conflictMessage}onKeepMine={() => resolve(c.model, c.entityId, c.data!, c.serverVersion)}onKeepTheirs={() => revert(c.model, c.entityId)}/>));
Declaring how a resource behaves offline
Every mirrored model has offline semantics whether or not anyone chose them. Left alone they are: mirror everything, ask a human about every conflict, no age limit, nothing kept off the wire. Those are reasonable defaults, and they are also exactly the kind of thing that should be stated rather than assumed, because offline products fail quietly and an assumption is invisible.
A sync: block in the resource definition states them:
name: Salefields:- name: referencetype: string- name: totaltype: float- name: payment_methodtype: string- name: draft_notetype: textsync:mode: offline_first # offline_first | online_only | read_onlyconflict: server_wins # manual (default) | server_wins | client_winsfields: [reference, total, payment_method]local_only: [draft_note] # never leaves the devicemax_offline_age: 72h
grit generate resource Sale --from sale.yaml
| Mode | Mirrored locally | Client may write |
|---|---|---|
| offline_first | Yes | Yes, through the outbox. The default. |
| read_only | Yes | No. The outbox refuses to accept one and the server refuses the push. |
| online_only | No | No. A pull for it is rejected rather than answered empty. |
read_only is for records the server authors on a user's behalf: an append-only ledger, an audit or provenance row, a result computed by a job, anything written through a hook a client cannot reproduce. It is a common shape rather than an exotic one, and neither of the other two modes fits it.
online_only means she cannot read a record about her own work offline, which is the wrong answer for a report she should be able to open on a train. offline_first declares the rows a client's to create, so the outbox queues a write that is guaranteed to fail and then parks it in front of her with whatever the server said. Every queued-and-failed write is a row somebody has to look at and dismiss.
conflict: server_wins is not the same thing, and that is worth being clear about because it is the nearest available-looking answer. It decides what happens when versionsdisagree, and a client-minted create has no version to disagree about, so it never runs.
const { data, readOnly } = useOfflineResource<CostLedger>("cost_ledgers")// readOnly is true, so hide the button rather than offering an action that throws.{!readOnly && <Button onClick={() => create({ amount: 5 })}>Add</Button>}
The three mutations stay on the returned object for a read_only resource rather than disappearing: their absence would only be knowable at runtime, so every call site would need a null check to satisfy TypeScript for a case most of them cannot be in. They reject with a message naming the mode, and readOnly is what a screen branches on.
grit sync doctor warns when a resource generated with --append-only is declared offline_first, because its updates and deletes are refused by the GORM guard and by a database trigger under that. Nothing is broken in such a project; the declaration simply reads as though it took effect. Creates are still legal on an append-only model, which is why it is a warning rather than an error.
| Conflict | What happens on a version mismatch |
|---|---|
| manual | The change is parked with both versions attached and a human decides. The default, because silently discarding somebody's work should be opt-in. |
| server_wins | The client's change is discarded and the server row replaces it locally. Nobody is prompted. For records a back office owns: stock, prices. |
| client_wins | The client's change overwrites the server's. For records with a single author, where the version check protects nothing. |
The policy is enforced on the server. A rule an old build can ignore is not a rule, so the decision is made where a request cannot argue with it.
The client refuses first
The server refusing a push is the backstop, not the useful part. Every queued-and-failed write is a row somebody has to look at and dismiss, about a record they did not create and cannot fix, and by the time they see it the write may have been carried around for three days. So the client declines to queue it at the keystroke instead.
That is only worth anything offline, because online the server would have said so anyway. Which means it cannot depend on asking the server. Both engines read their policy table in this order:
- What the server last said, persisted locally: in the device SQLite for the desktop app, in the adapter's metadata for the web. A client that has synced once never needs the network again to know what it may write.
- The compiled-in table, which is what makes the refusal work on an install that has never reached the server at all.
grit syncwritesapps/desktop/sync/policies_bootstrap.gofrom the project's own registrations, so there is no second list to keep in step by hand. offline_first, for a table nobody has heard of. Unknown means allow, so a resource generated after the installed build shipped is not broken offline.
A failed fetch keeps what the client had, and so does an empty answer: a project that removed every registration and a response shape that changed look identical from here, and forgetting is the costlier guess.
// apps/desktop: refused before anything is written or queued.err := engine.LocalCreate("cost_ledgers", "", map[string]interface{}{"amount": 5})var policyErr *sync.PolicyErrorif errors.As(err, &policyErr) {// Not a retry, and not a database failure. Advice() is the sentence// for the user; Error() names the table and the operation, for a log.show(policyErr.Advice())}
A typed error rather than a string, so a screen can tell a policy refusal from a disk failure and say something true about it. The same reason do() returns a *sync.APIError carrying the HTTP status: a 4xx will be a 4xx forever and must stop the retry, while a 5xx or a transport failure must back off and try again, and honouring that rule should not require parsing a status back out of an error message. APIError.Retryable() answers it, counting 408 and 429 as retryable because both are statements about now rather than about the request.
grit sync rewrites the compiled-in table every time it runs, and reports what it wrote. If a table is declared read_only and the desktop app still queues writes for it, that command not having been run is the first thing to check.
A refusal the server will repeat
Some pushes are refused on their merits. The plan does not cover another project, the permission is not granted, the row was deleted on the server. Sending the same payload again gets the same answer, so a change like that is parked rather than retried: its outbox row moves to failed, carrying the server's own code and message, and it is not counted as pending.
It used to be retried for ever. The row stayed queued, the pending badge counted it, and with auto-sync on that is one doomed request every thirty seconds for the life of the install, about a record the person cannot fix and must not dismiss without being told what it was.
status := engine.Status()status.Pending // waiting to gostatus.Failed // parked, waiting for a personparked, _ := engine.GetFailedChanges()for _, row := range parked {// row.ErrorCode and row.ErrorMsg are the server's words.// Not row.ConflictMsg: that field is named for conflicts, and a screen// built from the field name would show a plan limit in a merge dialog.show(row.Model, row.ErrorCode, row.ErrorMsg)}// When the reason is gone: the plan upgraded, the permission granted.engine.RetryChange("projects", id)
Nothing retries on its own, and a failed row never disappears on its own either. It is somebody's work, and the only things that move it are RetryChange and the revert the sync screen already has.
Which refusals are permanent
The server decides, and says so in the push result: PushResult.Permanent() and .Transient() set a retryable field the client reads. That is the right place for it, because the server is the only thing that knows what its own hooks answer: an entitlement guard refusing a row because the plan does not cover it is permanent for an unchanged payload, and no list compiled into a desktop build could know that code exists.
A client talking to a server too old to send the field falls back to the codes the framework itself emits, and treats anything it does not recognise as worth retrying. Of the two ways to be wrong, wasting a request is recoverable and hiding somebody's work is not. A CREATE_FAILED or an INTERNAL_ERROR is a database fault that may clear, so those are retried and the attempt count is kept: a row climbing it is a server problem rather than a payload one.
local_only is stripped on both sides: the client does not send it and the server would drop it anyway, which is what makes it a promise rather than a convention. max_offline_age is advisory by necessity, because a client that has not synced is by definition not talking to the server. What it buys is a client that can say so, through its own stale badge state, instead of showing three-day-old stock levels in green.
grit sync doctor
Everything this checks fails silently. A field allowlist naming a column that does not exist errors nowhere: it excludes the real column, and every client mirrors rows with the value missing. A model with no Version field cannot detect a conflict at all, so it takes whichever write landed last and nobody is told.
grit sync doctorSync configuration: 5 model(s) registeredblogs, invoices, sales, uploads, userserror sales: sync fields allowlist names "totl", which the model does not haveFix the name. An allowlist entry that matches nothing silently dropsthe real column from every mirror.info sales: server_wins: an offline edit is discarded if the server moved onThe user is not asked. Make sure the screen says so before they type.
It also reports a policy that is declared but not enforced, which happens when a project's sync handler predates policies. That is the worst state to be in: routes.go says server_wins, the handler keeps prompting, and the declaration reads as though it took effect.
Diagnostics in the app
An outbox that stopped draining three days ago looks exactly like an outbox with nothing in it. useSyncHealth is the difference: pending count, conflict count, the age of the oldest queued change, time since the last successful sync, and per-model row counts.
const { health } = useSyncHealth();if (!health) return <Spinner />;return (<dl><Stat label="Queued changes" value={health.pending} /><Stat label="Awaiting a decision" value={health.conflicts} /><Stat label="Oldest queued" value={health.oldestPendingAgeSeconds} unit="s" /><Stat label="Last synced" value={health.lastSyncAgeSeconds ?? "never"} />{health.stale && <Warning>Past the declared offline age limit</Warning>}</dl>);
Encryption at rest
On mobile and desktop this is real, and it belongs to the caller: SQLiteAdapter takes an already-open database, so hand it an SQLCipher connection whose key came from the OS keystore and the mirror is encrypted with no change on this side.
In a browser it is not offered, because it could not be honest. There is no keystore, so any key the page holds sits in JavaScript beside the data it is meant to protect, and anything with script access to the origin has both. An “encrypted IndexedDB” option would defend against a threat nobody has while implying it defends against the one people picture. Keep genuinely sensitive fields off the device with local_only, or mark the resource online_only.
Where the mirror lives
The engine holds no storage-specific code. It talks to a StorageAdapter, and three ship:
| Adapter | For | Notes |
|---|---|---|
| IndexedDBAdapter | Web, PWA | Keys on [model, id]; no size ceiling worth worrying about |
| SQLiteAdapter | Expo | expo-sqlite, WAL mode, the same three tables the desktop engine keeps |
| MemoryAdapter | Tests, server rendering | Nothing survives a reload, which is the point |
The web setup picks between IndexedDB and memory at runtime rather than assuming a browser: a Next.js server render has no IndexedDB, and a component that reaches for it there throws during render instead of degrading.
The desktop engine
Grit Desktop keeps its Go engine. It is the same wire protocol, the same record and outbox shapes, and the same conflict semantics, running in-process against GORM rather than over a storage interface. A row means the same thing on a laptop as it does on a phone.
