@repus/gist-sync

GitHub-login + Gist-backed cross-device sync of app data, extracted so more than one project can reuse it. Bring-your-own-storage: a user's personal data (favorites, tags, notes, settings…) lives in their own private GitHub Gist — you host no database and store no user data.

• . (core) — framework-agnostic engine: OAuth token lifecycle, gist I/O, direction detection, schema-driven 3-way merge, conflict handling, debounced pushes, backoff retries, keepalive flush. Zero runtime dependencies.
• ./react — a GistSyncProvider + useGistSync() hook.
• ./netlify — the stateless OAuth token-exchange broker (also runs on any serverless host).

Why this exists

GitHub's OAuth web flow needs a client secret to trade a code for a token, and its token endpoint sends no CORS headers — so a purely static SPA can't do it alone. The one server-side piece is a tiny stateless broker. Everything else (the token, the gist, the merge) is client-side. The hard, reusable part — detecting which side changed and merging both without a real backend — is what this package packages up. See the design notes at the bottom.

Install

Published to the public npm registry — no auth or .npmrc needed:

pnpm add @repus/gist-sync

1. Deploy the broker

Register a GitHub OAuth App for the project (one per project) with its Homepage and Authorization callback URL both set to the site root. Set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET in the host's server env, and expose the client id to the browser build (e.g. PUBLIC_GH_CLIENT_ID).

On Netlify, one file is enough:

// netlify/functions/github-oauth.ts
export { handler } from '@repus/gist-sync/netlify';

# netlify.toml
[functions]
  directory = "netlify/functions"

2. Describe your data (the schema)

The core treats domain fields opaquely except for how to merge each one. Declare that once. The field order also fixes the content fingerprint, so keep it stable.

import type { Schema } from '@repus/gist-sync';

const schema: Schema = {
  collections:   { kind: 'idKeyed', key: 'id',   label: 'Collection' },
  savedSearches: { kind: 'idKeyed', key: 'name', label: 'Saved search' },
  paperTags:     { kind: 'listMap' },   // Record<string, string[]> — union on conflict
  paperNotes:    { kind: 'scalarMap', label: 'Note' },
  readStatus:    { kind: 'scalarMap', label: 'Status' },
  // favorites:  { kind: 'stringSet' }, // string[] as a set (union honoring deletes)
};

Merge primitives: idKeyed (objects keyed by a field), scalarMap (Record<string,string>), listMap (Record<string,string[]>, unions on conflict), stringSet (string[] as a set), replace (opaque last-writer), custom (your own (base, local, remote) => { value, conflicts }).

3a. Use it — React

import { GistSyncProvider, useGistSync } from '@repus/gist-sync/react';

<GistSyncProvider
  config={{
    clientId: import.meta.env.PUBLIC_GH_CLIENT_ID,
    brokerPath: '/.netlify/functions/github-oauth',
    gistFilename: 'myapp-config.json',
    appMarker: 'myapp',
  }}
  schema={schema}
  serialize={() => ({ app: 'myapp', version: 1, ...readMyState() })}
  apply={(bundle, opts) => writeMyState(bundle, opts?.merge)}
  onToast={(msg) => showToast(msg)}
>
  <App />
</GistSyncProvider>;

function SyncButton() {
  const { status, user, conflict, login, syncNow, resolveConflict } = useGistSync();
  // ...render login/status; render your own conflict UI from `conflict` and
  //    call resolveConflict('local' | 'cloud' | 'merge').
}

Call markLocalChange() after mutating your synced state to schedule a debounced background push.

3b. Use it — vanilla / any framework

import { createGistSync } from '@repus/gist-sync';

const sync = createGistSync({
  config: { clientId, brokerPath, gistFilename, appMarker },
  schema,
  ports: {
    serialize: () => currentBundle(),
    apply: (b, o) => applyBundle(b, o),
    onStatus: (s) => renderStatus(s),
    onToast: (m) => toast(m),
    onUser: (u) => renderUser(u),
    onConflict: (c) => (c ? openConflictUI(c) : closeConflictUI()),
  },
});

sync.handleOAuthCallback();      // on startup: consumes ?code=
// login button → sync.login()
// after editing synced state → sync.markLocalChange()
// manual sync → sync.syncNow()

How sync decides direction

Each device stores a SyncMeta after every sync: the remote updatedAt it last saw, a content fingerprint of its local data, and the last-synced bundle as a merge base. On sync it does a conditional GET (ETag → 304 when unchanged, not billed against the rate limit), then:

• only local changed → push
• only remote changed → pull
• both changed, same content → reconcile silently
• both changed, base known → 3-way merge; if every item is unambiguous, apply and push; otherwise surface a conflict for the host to resolve (local / cloud / merge)

The gist-scoped token lives only in the user's own storage; the broker keeps nothing. Scope is gist (least privilege).