How sync works
StashSync.app stores all your data in local IndexedDB storage on your device. This is the primary database — everything you create, edit, or delete is written locally first, instantly, with no round-trip to a server.
When you're online, changes are relayed to your other devices through a WebSocket sync server using CRDT (Conflict-free Replicated Data Types) technology. CRDTs guarantee that concurrent edits from multiple devices are always merged correctly without manual conflict resolution.
Sync status indicator
A sync status pill appears in the bottom-right corner of the app whenever your connection is not fully synced. It shows your current state:
| Status | Meaning |
|---|---|
| Synced | Connected to the sync server; changes sync in real time. The pill fades away after a moment. |
| Sync paused | The WebSocket has disconnected (e.g. after 5 minutes of inactivity or when the browser tab is hidden), but your device still has internet. Your changes are safely stored locally. |
| No connection | No internet connection; all changes are queued locally and will sync when you reconnect. |
When the status is Sync paused or No connection, click the pill to manually trigger a reconnect attempt. The pill shows Reconnecting… while retrying.
Offline mode
When you lose your internet connection:
- The sync indicator switches to No connection.
- All changes are stored locally and will sync automatically when you reconnect.
Reading, writing, organizing, and searching all work offline. The following require an active connection:
- Uploading new files
- Opening the file picker
- Viewing file contents that have not been pinned for offline access (see Offline access on the Files page)
- Creating or revoking share links
- Emptying trash when it contains files
Offline page
If your browser session itself becomes unavailable (e.g. you navigate away and back to the app while offline), you can still browse your content at /~offline. This page serves your cached library directly from the local database.
Multi-device setup
You can use StashSync.app on as many devices as you want with the same account. Simply sign in on each device and StashSync.app will:
- Download your full library to local storage on first load.
- Connect to the sync server to receive any changes made on other devices.
- Send any local changes you've made to other devices.
Conflict resolution
StashSync.app uses Yjs, a CRDT library, to handle concurrent edits. If you edit the same note on two offline devices and then reconnect, the changes are merged automatically. You will not be asked to manually resolve conflicts.
Account switching
If a different user signs in on the same device, StashSync.app clears the previous user's local database and loads the new user's data. Each user's data is fully isolated.