Visit Website →
← Back to blog

Local First Software: 6 Step Developer Checklist for CRDTs and Logs

October 6, 2026
Local First Software: 6 Step Developer Checklist for CRDTs and Logs

Local-first software keeps the primary copy of user data on a person's own device and syncs changes in the background, rather than treating a remote server as the source of truth. This matters because it gives people offline availability, genuine data ownership, and resilience if a vendor shuts down. Ahead, we cover the guiding principles, the core technology (CRDTs), the trade-offs, and the practical steps to build it.

TL;DR:

  • Local-first applications prioritize the device as the primary data source, enabling offline use, data ownership, and resilience without relying on central servers.
  • CRDTs are the core technology that ensures seamless, conflict-free merging of concurrent edits across multiple devices without centralized arbitration.
  • Implementing local-first systems requires managing append-only logs, log compaction, and secure encryption, which add complexity and ongoing maintenance costs.
  • End-to-end encryption prevents server-side access to data but limits server-side features like search and analytics, demanding alternative solutions like metadata or selective encryption.
  • While valuable for offline resilience and privacy, local-first architecture increases engineering overhead and is less suitable for features like large-scale search and centralized compliance reporting.
Lawtonpdf
Keep Sensitive Documents Local
LawtonPDF processes PDFs and other documents locally on Windows, helping teams compare and manage sensitive files without sending them elsewhere.
Visit LawtonPDF

Table of Contents

What local-first means in practice

Cloud-first applications treat the server as the authoritative record: your device holds a cache, and every meaningful write waits on a round trip to that server. Local-first flips this. Your device holds the authoritative copy, and the network becomes a convenience for sync, not a requirement for basic use. This single change in where authority lives affects everything from how fast an app feels to what happens when someone loses internet access on a flight.

Offline-first is a related but narrower idea: it usually means an app caches data locally and queues writes until connectivity returns, but the server still owns the canonical state once sync completes. Local-first goes further, since your device's copy stays authoritative even after sync, and multiple devices reconcile as peers rather than clients reporting to a boss.

Three topologies show up repeatedly in working systems:

  • Server-assisted replication: a server relays encrypted changes between devices without reading or arbitrating them.
  • Peer-to-peer sync: devices exchange changes directly over a local network or a relay, with no central server at all.
  • File-based handoff: changes move through shared files or removable storage, common in air-gapped or highly regulated settings.

Whatever the topology, users expect the same experience: operations complete instantly on-device, the UI reflects that change immediately, and sync happens quietly in the background with eventual consistency across devices.

The seven ideals that define local-first design

The canonical definition of local-first comes from a well-known Ink & Switch essay, which lays out seven ideals that distinguish the pattern from ordinary offline support. Each one carries a direct implication for how you build.

  • Fast: critical operations run against local data, so there is no spinner for a simple edit or search.
  • Multi-device: a person's data should converge correctly whether they edit from a laptop, phone, or tablet.
  • Offline-capable: the app works fully with no network, not just in a degraded read-only mode.
  • Collaborative: multiple people can edit concurrently, and the system merges their changes without a lock.
  • Long-lived: data outlives any single vendor, so a shutdown or pricing change does not erase a person's work.
  • Encrypted end to end: the contents stay unreadable to the server, even one that helps relay or back up data.
  • User-controlled: people can access, export, and manage their own data without asking permission.

No existing system nails all seven at once, and the essay treats them as a design target rather than a checklist you tick off. The honest framing is that the conceptual shift, rethinking UI feedback for eventual consistency and letting go of a request-response mental model, is often harder than any single algorithm.

Core technologies: CRDTs, operational logs, and alternatives

Conflict-free Replicated Data Types, or CRDTs, are the mechanism most local-first systems lean on to make concurrent edits converge. A CRDT is a data structure with a defined merge function: when two devices each apply changes independently and later exchange them, the merge always produces the same result regardless of order. That mathematical guarantee is what lets multiple people edit the same document without a central lock deciding who goes first, and modern CRDT implementations support rich data types beyond plain text, including maps, lists, and nested structures.

Operational Transformation, the technique behind early collaborative editors like Google Docs, solves a similar problem but requires a central server to transform and order operations correctly. OT still works well when you already have a trusted server mediating every edit. CRDTs matter more for local-first specifically because they allow correct merging without that central authority, which fits a world where the device, not the server, holds the primary copy.

Automerge is the most widely used CRDT library for this pattern. It represents a document as a sequence of changes, lets you load and save that history, and automatically merges concurrent edits from different replicas.

A concise framing from the research: "Servers remain, but their role shifts." This reframing, drawn from the peer-reviewed local-first paradigm described in ACM proceedings, captures the core engineering move: servers become relays, backups, and discovery points rather than owners of the canonical dataset.

  • CRDTs guarantee convergence mathematically, removing the need for manual conflict arbitration in most cases.
  • OT requires central coordination, which makes it a poor fit for peer-to-peer or fully offline scenarios.
  • Automerge manages history as an append-only log of changes that any replica can replay and merge.

Storage, logs, and compaction: keeping local data durable

Once you commit to a CRDT or similar approach, you need somewhere durable to put the data. In browsers, IndexedDB is the standard choice for structured local storage, and the File System Access API gives you direct file handles when a browser-based app needs file-like semantics. On desktop, SQLite and plain local files remain the most common backends, since both handle concurrent reads well and survive process crashes.

Most CRDT libraries, Automerge included, store data as an append-only log of changes rather than a single mutable blob. That log is what lets any device replay history and merge correctly, but it also grows without bound unless you manage it.

  1. Write incoming changes to the append-only log first, so nothing is lost if the app crashes mid-write.
  2. Periodically compact the log into a snapshot that represents current state without the full history.
  3. Keep the snapshot for fast loads, and retain only the log entries needed for incremental merges with peers that have not yet synced.
  4. Choose a storage adapter that supports atomic writes and concurrent readers, since a torn write during compaction can corrupt the whole document.

Automerge's storage documentation is explicit that production readiness depends as much on compaction strategy as on CRDT correctness: an uncompacted change log degrades load time and can bloat local storage well past what the actual data would require. Range queries and concurrent access are the two failure points worth testing early, since a storage adapter that works fine for single-user prototypes can stall under real multi-device load.

Pro Tip: Write a test that loads your largest realistic document from an uncompacted log and times it, then compare against the compacted snapshot before you ship.

Event log compressed into durable snapshot

Security, privacy, and the real cost of encryption

End-to-end encryption is what makes the local-first promise of privacy credible rather than aspirational. Without it, a server that relays or backs up your data can still read the contents, which defeats the point of keeping the device authoritative. With E2EE, the server only ever sees encrypted bytes, even when it is actively helping with sync or storage.

Encrypted data crossing relay between devices

That protection comes with real feature costs. Server-side full-text search, filtering, and analytics all depend on reading plaintext, so an encrypted payload makes those features impossible to run centrally without exposing more than intended. Teams that need any server-side visibility typically solve this with sidecar metadata (small, deliberately unencrypted fields the server can index) or selective encryption, where only the sensitive fields are protected.

Key management is the other hard problem. Keys can be user-derived from a password or passphrase, or provisioned through a key server, and each choice trades convenience against risk. Losing a key without a recovery flow in place means the data behind it is gone permanently, so that risk needs to be surfaced to users plainly rather than buried in settings.

  • E2EE prevents the server from reading contents, but also blocks server-side search and analytics on that data.
  • Sidecar metadata or selective encryption can restore limited server features without exposing full contents.
  • Key rotation and recovery flows need to exist before launch, since key loss is effectively irreversible.

For regulated teams, the broader question of where processing happens and who can access it is worth reading in more depth in our comparison of on-premise and cloud security models for document-sensitive workflows.

When local-first is not the right fit

Local-first is not free architecturally, and it is worth being honest about where it costs more than it saves. Conflict resolution logic, data migrations across schema versions, and a toolchain built around CRDTs instead of simple REST calls all add engineering time that a server-authoritative app would not need.

Operationally, local storage that never shrinks becomes a real support burden: devices run out of space, sync bandwidth adds up across many peers, and users who lose a device or a key need a recovery path your team has to build and maintain.

Certain features also just fit cloud-first architectures better. Full-text search across a large shared dataset, centralized analytics dashboards, and regulatory reporting that requires a single queryable system of record are all easier to deliver when a server holds the canonical data and can index it freely.

  • Conflict resolution and schema migrations add engineering overhead a simple client-server app avoids.
  • Storage growth and key recovery create ongoing support costs that scale with your user base.
  • Centralized search, analytics, and compliance reporting are harder to deliver without a server-owned dataset.

Procurement teams evaluating vendor software for regulated environments, such as the considerations covered in comparisons of HR software for law firms, often weigh these same trade-offs between centralized visibility and local control.

A developer checklist for prototyping local-first features

Building local-first well is less about picking the right library on day one and more about sequencing your prototype so each layer gets validated before you add the next.

  1. Decide your data model and sync topology first: a single document, a collection, or a tree, and whether sync will be server-assisted or peer-to-peer.
  2. Choose between a CRDT library and a custom server-side merge strategy based on how much concurrent editing you actually expect.
  3. Build a single-device prototype that reads and writes locally with no sync at all, so you can validate the data model in isolation.
  4. Add durable persistence next: confirm writes survive an app crash and a cold restart before introducing any network code.
  5. Introduce two-device sync over a simple relay, and watch how the UI behaves during the gap between a local write and a confirmed merge.
  6. Add peer discovery and real network conditions last, once the merge logic itself is proven correct.

Testing deserves its own pass once the prototype works end to end. Simulate network partitions deliberately, since a feature that only gets tested on a stable connection will surprise you in the field. Run compaction tests against your largest realistic dataset, rehearse schema migrations against old local data, and spend real time on the UX of eventual consistency, specifically what the interface shows in the seconds between a local commit and a confirmed cross-device merge.

Pro Tip: Build your partition simulation before you build your sync protocol. It is much easier to design merge behavior when you can already watch it fail safely.

Teams without in-house experience in this architecture sometimes bring in outside help for the prototype phase. Custom software development agencies that have built sync-heavy applications before can shortcut some of the trial and error in steps three through six.

LawtonPDF as a working example of local processing

LawtonPDF runs every PDF and document operation, including merging, comparing, redacting, and watermarking, entirely on the user's own computer. No file is uploaded to a server to be processed, which maps directly to several of the seven ideals: longevity, since your documents and tools do not depend on a vendor's servers staying online, and offline access, which matters for legal, healthcare, and finance teams that cannot risk sensitive files leaving their network. Our guide to audit-ready offline controls and our piece on centralized document administration walk through how local processing supports governance and compliance in regulated environments.

Where this pattern is headed

Local-first is maturing, but the gap is not in CRDT theory anymore, it is in tooling. Storage adapters still need better defaults for compaction, and almost no framework yet offers a polished UX pattern for communicating eventual consistency to non-technical users. Our honest recommendation is incremental: adopt local-first for the features that most need offline resilience and privacy, and keep a hybrid model everywhere else rather than rewriting an entire architecture at once.

— Lawton

Try local document processing with LawtonPDF

If the privacy and offline benefits of local-first design appeal to you, our own tools put that same principle to work for everyday document handling. We process every file, comparisons, merges, redactions, watermarks, on your own machine, so nothing leaves your network to get the job done. That matters most for legal, finance, and healthcare teams who need PDF comparison and organizing tools that keep sensitive files off third-party servers entirely, with team administration built in for larger groups.

Lawtonpdf

Our free tier covers core tools at no cost, and paid plans add the comparison and administration features regulated teams need. Pricing details for all three live on our pricing page, or you can explore the full tool set before deciding which plan fits your workflow.

FAQ

What is the best free and open-source software for local-first apps?

Automerge is the most widely used open-source library for building local-first apps, since it implements CRDTs and manages the append-only change log and merging under the hood. It is free to use and actively maintained on GitHub, with documentation covering storage and compaction in detail.

What is considered the world's first software?

This question falls outside the scope of local-first architecture and document tooling, and no source in this article addresses it. We would rather point you toward the local-first resources above than guess at an answer we cannot back up.

What are low-code platforms and how do they relate to local-first design?

Low-code platforms let people build applications through visual interfaces and prebuilt components rather than hand-written code, which speeds up development for standard business apps. They are a separate category from local-first architecture, though some platforms are beginning to add offline-capable or local-storage modes as the pattern gains traction.

What is the best free software for small businesses that need local document processing?

We offer a free tier that covers core PDF tools, including organizing and basic editing, with every operation run locally on your machine rather than uploaded to a server. Small businesses that need the added comparison and team administration features can move to the paid Plus or Business plans listed on our pricing page.

How do CRDTs differ from traditional server-based conflict resolution?

CRDTs merge concurrent changes using a mathematically defined function that always produces the same result regardless of the order changes arrive, so no central server needs to arbitrate conflicts. Traditional server-based resolution, including Operational Transformation, requires a trusted server to transform and order every edit, which works well in connected environments but breaks down for offline or peer-to-peer use.

Sources