How Heaper Works

You don't need to read this page to use Heaper. It explains what happens behind the scenes, and helps you decide between Heaper Cloud, your own server or no server at all.

Your device comes first

Heaper is local-first. Everything you write is saved on your device first:

  1. A change is saved instantly, with or without internet.
  2. When a connection is available, Heaper syncs it in the background.
  3. If two devices changed the same note while offline, Heaper merges both changes automatically.

That's why Heaper never shows a "conflicted copy" or asks which version to keep. The technique behind it is a CRDT, see What is a CRDT?

Three ways to keep your data

On this device onlyHeaper CloudYour own server
Account neededNoEmailSeed phrase
Sync between devicesNoYesYes
Share with othersNoYesYes
Who stores your dataYouHeaper, in EuropeYou
SetupNoneNoneSelf-Hosting

You can start on one device and add sync later. You can also use several heaps on different servers side by side.

Servers and devices

With a server, your data has a home base:

  • The server keeps the full copy of everything. Your files stay normal files in normal folders, so you can open them without Heaper. Notes, tags and other details are stored in a PostgreSQL database that you can also access on your own server.
  • Your devices keep what you need. Phones and laptops store previews and details for everything, and download full files when you open them. You can choose files to always keep on a device. See Storage on Your Device.

This way a phone with little storage can still browse a heap of hundreds of gigabytes.

Bringing in existing files

On your own server, Heaper can scan folders you already have and add every file and folder to a heap, with previews. The files stay where they are. This is the fastest way to bring in large photo or document archives. See Files & Importing.

Technology used

  • Yjs: the CRDT that merges edits
  • SQLite: the local database on each device
  • PostgreSQL: the database on the server
  • Rust: fast sync and file transfer on every platform
  • Go: the server
  • Vue and TipTap: the app and its editor

For developers