Local-First Software.

Engineering Deep Dive

Local-First
Software.

Work first. Sync later. A new way to think about how apps handle your data — and why it changes everything about how users experience software.

12 min read

System Design

Engineering

Scroll to read

The Problem

Every click is a round trip you didn't ask for.

The traditional web treats your browser like a dumb terminal. Press a button — a request flies across the internet, hits a server, runs logic, and eventually something comes back. Fine when fast. Falls apart everywhere else.

👤

You

→

📶

Network

→

🖥

Server

→

🗄

→

📱

Response

⚡

Latency

Even fast servers add 100–400ms per request. Multiply by every action.

📵

Offline = Dead

Lose signal and the app stops completely. No network, no product.

📈

Infra Cost

Every user action is a server load. Scale means money. Constantly.

⏳

Spinners Everywhere

Loading states are UX patches for architecture decisions.

The Shift

What if the device was the source of truth — at least for now?

Move logic and storage onto the device. When you type, it saves instantly — no server involved. The network becomes a background concern, not a blocker. Think how native apps always worked. Calendar events save immediately. Photos land on your device before iCloud ever sees them.

💡

Old thinking: Server is truth, client is a view.

New thinking: Device is truth, server is a sync target.

How It Works

Write locally → Update UI → Sync later.

Three things happen with every action. They just don't have to happen at the same time.

🗄

Save to Local DB

Data writes to IndexedDB immediately. No network, no waiting. This is what makes it feel instant.

🖥

Update the UI

The interface reads from local storage and re-renders in milliseconds. Optimistic by default, no spinners needed.

🔄

Sync in Background

A worker queues the change and sends it to the server when connectivity is available. Retries and deduplication are handled automatically.

Real-Life Example

Writing a note while offline.

Your notes app shouldn't care if you have WiFi. Watch what happens when you type with no connection — the UI never blocks, the data never disappears.

notes.app — meeting.md

Offline — saved locally

ℹ️

Under the hood: keypress → saved to IndexedDB with syncStatus: "pending" → worker detects connection → pushes to /api/sync → marked synced.

Technical Implementation

IndexedDB + a sync status flag.

Most teams use Dexie.js as a wrapper around IndexedDB. Every write tags the record with a syncStatus. That's the whole trick.

javascript — db.js

// Every write tags the record with syncStatus
async function saveNote(title, content) {
  const id = await db.notes.add({
    title,
    content,
    updatedAt: new Date().toISOString(),
    syncStatus: 'pending'   // ← the key field
  })
  scheduleSyncJob()   // non-blocking
  return id
}

Any record tagged "pending" needs to be pushed. No Redis, no broker, no extra infra.

Sync Engine

Pushing pending records when back online.

The sync job fires when the browser detects a connection — or polls every 30 seconds as a fallback. It reads pending records, batches them, and POSTs to one endpoint.

javascript — sync-worker.js

async function runSyncJob() {
  const pending = await db.notes
    .where('syncStatus').equals('pending').toArray()

  if (pending.length === 0) return

  const res = await fetch('/api/sync', {
    method: 'POST',
    body: JSON.stringify({ records: pending })
  })

  if (res.ok) {
    await db.notes.where('id').anyOf(ids)
      .modify({ syncStatus: 'synced' })
  }
}

window.addEventListener('online', runSyncJob)
setInterval(runSyncJob, 30_000)

Conflict Handling

Two devices. One note. Who wins?

If you edit a note on your phone while your laptop is offline, and both come back online — which version wins? You have options.

Simple

Last Write Wins

Compare updatedAt timestamps. Newer wins. Easy to build, but concurrent edits can be silently lost.

Advanced

CRDTs

Conflict-free Replicated Data Types. Any two states can always be merged without conflicts. Zero data loss. Used by Figma and Linear.

javascript — conflict.js

function resolveConflict(local, server) {
  const lTime = new Date(local.updatedAt).getTime()
  const sTime = new Date(server.updatedAt).getTime()
  return lTime > sTime ? local : server
}

Security

Local-first ≠ trust the client.

Moving logic to the device creates new attack surfaces. Treat everything arriving at your sync endpoint as potentially hostile.

🛡

Never trust client data

Validate every field server-side. A client can send any timestamp it wants.

🔑

Encrypt at rest

IndexedDB is readable by any script on your origin. Encrypt sensitive data before writing locally.

🔒

Authenticate every sync call

Every /api/sync request needs a valid auth token.

📊

Rate-limit the sync endpoint

Cap batch sizes and apply rate limiting per user. Unbounded endpoints are easy DoS targets.

Go local-first.

Local DB + sync status flag + background worker. That's the core. CRDTs, encryption, conflict resolution — all layered in as you need them.

The best apps feel like they live on your device. This is how you get there.

Local-FirstSoftware.

Every click is a round trip you didn't ask for.

Latency

Offline = Dead

Infra Cost

Spinners Everywhere

What if the device was the source of truth — at least for now?

Write locally → Update UI → Sync later.

Save to Local DB

Update the UI

Sync in Background

Writing a note while offline.

IndexedDB + a sync status flag.

Pushing pending records when back online.

Two devices. One note. Who wins?

Last Write Wins

CRDTs

Local-first ≠ trust the client.

Never trust client data

Encrypt at rest

Authenticate every sync call

Rate-limit the sync endpoint

Local-First
Software.