A single-user Cloudflare Worker that keeps the userscript's settings and visited history in a Durable Object, so the history survives a userscript-manager reinstall and follows you between devices.
One object, one bearer token. Anyone with that token can read and write the whole history, so treat it like a password.
A Durable Object is single-threaded and strongly consistent, so the read-merge-write each sync performs is serialized: two devices syncing in the same second queue behind one another instead of both merging into the same stale base. Its storage is SQLite, so history is rows rather than one blob, and devices exchange only what changed — an idle page load costs about 150 bytes each way, against roughly 450 KB for a full history under the old whole-document protocol.
cd worker
npx wrangler login
openssl rand -base64 32 # your access token — keep a copy
npx wrangler secret put SYNC_TOKEN # paste the token when prompted
npx wrangler deployNo namespace to create and nothing to paste into wrangler.toml.
workers_dev = false is set, so the worker has no *.workers.dev URL: those subdomains
are guessable, and the history behind this one is worth not advertising. Give it a route on a
domain you own instead — uncomment routes in wrangler.toml and point it at a hostname in
a zone on the same Cloudflare account:
routes = [
{ pattern = "sync.example.com", custom_domain = true },
]Deploying with workers_dev = false and no route leaves the worker unreachable. If you would
rather use the free subdomain, comment workers_dev out and wrangler deploy prints the URL,
e.g. https://javstore-sync.<subdomain>.workers.dev.
Workers & Pages → javstore-sync → Settings → Builds → Connect links the worker to
this repository, so every push to main deploys it:
| Setting | Value |
|---|---|
| Production branch | main |
| Build command | (empty — there is nothing to build) |
| Deploy command | npx wrangler deploy |
| Root directory | /worker — wrangler.toml lives here, not at the repository root |
The SYNC_TOKEN secret and any route or custom domain stay on the worker, so they survive a
rebuild. To confirm a deploy landed, open the userscript's Cloud sync panel and press
Sync now: the worker version shown there should match the release.
Open the JVS panel on JavStore → Cloud sync:
- Worker endpoint — your route, or the URL from
wrangler deploy(any path works;/statereads well). Changing the endpoint later is safe: the device notices it is a different worker and re-uploads its history in full. - Access token — the token you generated.
- Tick Sync to my Cloudflare Worker, then Save sync settings.
Repeat on every device with the same URL and token. Each device syncs on load, when its tab regains focus, a few seconds after a visit, on the interval you set, and on Sync now.
Uncomment the [[kv_namespaces]] block in wrangler.toml, fill in your old namespace id and
deploy. The worker imports that document into the Durable Object on its first request, once.
After a sync you can delete the binding and the namespace.
Devices still running 6.2.0 keep working against this worker — it answers the old whole-document protocol as well — and a 6.3.0 device falls back to that protocol if it finds an old worker, so the two can be upgraded in either order.
Settings merge setting by setting on their own timestamps (meta.settingTimes). Settings stored
by an earlier worker, or sent by a device older than 6.6.0, count as stamped at their single
settingsUpdatedAt. Redeploy the worker when you move to 6.6.0: an older worker still keeps
whichever device's settings object is newest as a whole.
Every route requires Authorization: Bearer <SYNC_TOKEN>; the path is ignored.
| Method | Body | Answer |
|---|---|---|
GET |
— | { worker, "state": <whole document> }, for backups |
POST |
{ cursor, meta, changes[], limit? } |
{ worker, cursor, more, meta, changes[] } |
POST |
{ "state": <document> } (6.2.0 clients) |
{ worker, "state": <whole document> } |
OPTIONS |
— | CORS preflight |
worker is the worker's version (from 6.7.0). The userscript shows it in the Cloud sync
panel and flags a worker that is behind it.
A delta POST hands over the entries the device has touched since its last push and asks
for everything recorded after cursor. Entries are last-writer-wins on their own event
timestamp, with a deletion winning a tie. A device that pushes an entry older than the
stored one is handed the winner back, so it cannot stay wrong about it.
Visited history is append-only: the worker ignores a device's visit deletions and its
resetAt and prunedBefore horizons (from 6.10.0), and always reports both horizons as 0.
Clearing history, retention pruning, unmarking a card and a backup import therefore change
only the device they happen on. Per-card override removals still apply.
The object keeps up to 50,000 visited entries, dropping the oldest beyond that (a device keeps its newest 5,000), and expires override tombstones after 90 days.
- Costs nothing in practice: a sync is one object request, and idle syncs move a few hundred bytes. SQLite-backed Durable Objects are free-plan eligible — check Cloudflare's current limits if you sync unusually often.
- Rotating the token:
npx wrangler secret put SYNC_TOKEN, then update it in the panel on each device. - Backing up the history:
curl -H "Authorization: Bearer $TOKEN" https://<your-worker>/state > backup.json. That file is also a valid Import backup file for the panel.