Local-first notes: offline by default, synced when you're back

Local-first software keeps the main copy of your data on your own device and uses the server as a helper: it carries changes between your devices and keeps a copy in case one of them is lost. For a notes app, that means you can open, read and write notes without a connection, on a plane or in a basement, and everything syncs when you're back online.

This guide explains how local-first differs from "offline-first" and ordinary cloud apps, what happens when two devices edit the same note, and where the approach has real limits. Our example is Cappa, the notes app we build, including the parts it doesn't do.

What is local-first software?

The term comes from a 2019 essay by the research lab Ink & Switch, Local-first software: you own your data, in spite of the cloud, by Martin Kleppmann, Adam Wiggins, Peter van Hardenberg and Mark McGranaghan. Their core idea is a swap of roles. In most apps today the server holds the real copy and your phone shows you a view of it. In local-first software, the copy on your laptop or phone is the primary one. In the authors' words, servers "hold secondary copies of your data in order to assist with access from multiple devices."

An everyday picture: a cloud-first app is like a notebook kept at the library. You can read it whenever you visit, but when the library is closed, you have nothing. A local-first app is a notebook in your bag, with a courier who makes sure the same pages appear in your other notebooks at home and at work.

The essay sets out seven ideals for this kind of software. Here they are in plain terms:

1. No spinners. Your work opens instantly because it's already on your device.
2. Your work is not trapped on one device. It shows up on your laptop, phone and tablet.
3. The network is optional. You can read and edit without a connection.
4. Seamless collaboration. Several people can work on the same thing without clobbering each other.
5. The Long Now. Your data stays readable for years, even if the company or app disappears.
6. Security and privacy by default. The server shouldn't be able to read everything you write.
7. You retain ultimate ownership and control. You can copy, export and delete your data on your own terms.

The authors admit that existing technologies meet some of these goals but none meets them all. Further down, we check Cappa against them honestly.

Local-first vs offline-first vs cloud-first

These three terms often get mixed up. Here is how they're usually meant.

• Cloud-first (the default for most web apps): the real data lives on the provider's servers. Your device downloads what it needs to show you. No connection usually means a spinner, an error or a read-only view.
• Offline-first: a design approach that keeps the app working when the connection drops, typically by caching data on the device and sending changes later. It says nothing about who owns the data or which copy counts; the server's copy is often still "the real one".
• Local-first: offline support is just the start. The device copy is the primary copy, the server is a helper, and the goals include privacy, longevity and ownership.

In short, every local-first app works offline, but not every offline-first app is local-first.

How Cappa works offline

Every modern browser has a small database built in, called IndexedDB, that a website can use to store data on your device. Cappa keeps two things there:

• an encrypted copy of your notes and settings, the same sealed records the server stores;
• a queue of changes (sometimes called an outbox): every edit you've made on this device that the server hasn't confirmed yet.

The app itself, meaning the page and its scripts, is kept offline by a service worker, a small helper the browser runs for the site. Together this means that once you've opened your account on a device and the first sync has finished, you can open Cappa with no connection at all, unlock it with your master password and keep writing. Your notes are decrypted in the browser only while the app is unlocked. (If you want the details of that encryption, see our guide to end-to-end encrypted notes.)

There's one requirement worth stating plainly: offline works on devices where you've already used your account. A brand new phone has nothing stored yet, so the first opening needs a connection.

What the status labels mean

Cappa shows two small indicators next to the note: one for saving on this device, one for syncing with the server. They answer different questions.

How sync works when you're back online

Picture the server as a courier with a locked depot. Your devices drop off sealed envelopes (encrypted notes) and pick up the ones addressed to them. The courier knows how big each envelope is and when it arrived, but can't open it. The server does keep a copy of every envelope, which is what lets a new device download your notes. It just isn't the place your notes are read or edited.

Laptop on a plane

You edit a note. Each change is encrypted and saved locally, then waits in the queue.

back online: send sealed changes

Server as courier

Stores the encrypted records and their version numbers. It can't read them.

next check, within seconds

Your phone

Downloads the new records, decrypts them and merges them with its own changes.

When does Cappa sync?

While Cappa is open and visible, it checks with the server every 5 seconds. It also syncs as soon as the connection comes back, when you switch back to its window, and when you click the sync label. When the tab is hidden, polling pauses. After you close Cappa, it doesn't sync in the background, so if you edited offline, open the app once you're connected and let it finish before you switch devices.

Version numbers stop accidental overwrites

Each note on the server carries a version number, called a revision. When your device sends a change, it also says which revision it started from: "this is my edit to version 7". The server accepts it only if the note is still at version 7. If another device got there first, the server refuses, and your device downloads the newer version, merges and tries again. Programmers call this compare-and-swap. Each change also carries its own ID, so if a connection drops mid-send and the device retries, the server doesn't save the same change twice.

What happens when two devices edit the same note?

This is the classic sync conflict, and it's where many sync systems quietly lose text. There are two lazy answers: "the last device to sync wins" (the other edit disappears) or "stop and ask the user to compare two walls of text". Cappa does something closer to what software developers use for code: a three-way merge.

Three-way merge

A way to combine two edited versions of the same text by comparing each of them with the last version they had in common. Changes made on only one side are kept; changes to different lines are combined; only changes to the same lines need a decision.

To make that possible, Cappa keeps the last version both sides agreed on (encrypted, like everything else) alongside your local edit until the server confirms it. Here's what that looks like with a packing list edited on two devices while both were offline:

The phone changed line 3, and the laptop added line 5. Neither touched the other's lines, so both edits survive and you get one note with both changes.

Now suppose both devices had changed the same line: the laptop wrote "sunscreen SPF 50" and the phone "sunscreen, travel size". There's no way to know which you meant. Cappa keeps the more recently edited version in the note and saves the other one as a separate note whose title ends in "conflict copy". Nothing disappears; you pick what to keep and delete the copy.

Deleted notes stay deleted

Deletion needs care too. If your laptop was offline for a month and you deleted a note on your phone in the meantime, the laptop still has that note. When it reconnects, a naive sync might upload it again and bring the note back from the dead.

Cappa prevents this with tombstones: when you delete a note, the server keeps a small marker saying "this note was deleted", without its content. A device returning from a long time offline sees the marker and removes its copy instead of resurrecting it. Cappa doesn't clean these markers up over time, precisely so that a device that comes back after months still gets the message.

And if the timing clashes, meaning a note was deleted on one device while it was edited on another, Cappa errs on the side of keeping text. Depending on which happened later, the edited version is kept either as the note itself or as a separate copy, and in some cases a short "Deletion conflict" note explains what happened.

One open tab per vault

Two tabs writing to the same local database at once would need careful coordination, much like two devices do. Cappa takes the simpler, safer route by design: only one tab can have your vault unlocked at a time, enforced with the browser's Web Locks API. If you open it in a second tab, that tab refuses with "This vault is already open in another tab." It's a small inconvenience that keeps you from creating conflicts with yourself.

Honest limits of local-first notes

Local-first moves your notes closer to you, which also means your device's storage matters more.

A few habits cover most of these risks:

• Before a trip or before switching devices, open Cappa while you're online and wait until the label says "Synced".
• On an iPhone or iPad, add Cappa to your Home Screen rather than only using it in a Safari tab.
• Export your notes now and then from Settings → Data: either readable Markdown or TXT files, or a versioned backup file. Keep in mind that exports are not encrypted, so store them somewhere you trust. Because the notes are plain Markdown, they'll open in almost any editor; our Markdown guide for notes covers the basics.

How local-first is Cappa, really?

Measured against the seven ideals, here's our honest assessment:

One technical note for the curious: the Ink & Switch essay argues for CRDTs, data structures designed so that edits from many people always merge automatically. Cappa uses the older, Git-style three-way merge, which suits a single person editing text across a few devices, and falls back to keeping both versions when it can't be sure.

If you want to organize what you write once it's safely on your devices, see our guide on how to organize notes. And if you'd like to try the editor itself, the demo runs entirely in one browser tab. It doesn't sync or store anything, so it shows the writing experience, not the offline sync.

FAQ

Does Cappa work without an internet connection?

Yes, on any device where you've already signed in and completed the first sync. You can unlock with your master password, read and edit notes, and your changes wait in a queue until you're back online. Signing in on a new device, first sync and account recovery need a connection.

What's the difference between local-first and offline-first?

Offline-first describes an app that keeps working when the connection drops, usually by caching data. Local-first goes further: the copy on your device is the primary one, the server is a helper, and the design aims at privacy, longevity and your ownership of the data.

Will I lose text in a sync conflict?

Cappa is designed not to drop text silently. Edits to different lines of the same note are combined. When two devices change the same lines, the note keeps the more recent version and the other one is saved as a separate "conflict copy" note for you to review.

If I clear my browser data, are my notes gone?

The copy on that device is gone, including any changes that hadn't synced yet. Everything that already reached the server comes back after you sign in again on that device, since your notes download and decrypt locally. That's why it's worth checking for "Synced" before clearing anything.

Is sync the same as a backup?

No. Sync makes your devices agree, so a deletion or an unwanted edit spreads to all of them. A backup is a copy you can go back to. Export your notes from Settings → Data from time to time and keep the file somewhere safe.